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PREFACE 


The VAX/VMS Guide to Writing a Device Driver provides the information 
needed to write a device driver that runs under VAX/VMS Version 2.0 
and to load that driver into the operating system. VAX/VMS makes no 
guarantee that drivers written for VAX/VMS Versions 1.0, 1.5 and 2.0 
will execute without modification on subsequent versions of the 
operating system. While the intent is to maintain the existing 
interface, some unavoidable changes may occur as new features are 
added. The use of internal executive interfaces other than those 
described in this manual is discouraged. 


INTENDED AUDIENCE 


This manual is intended for system programmers.) who are already 
familiar with the VAX-11 processor and the VAX/VMS operating system. 
The manual focuses on writing drivers for devices attached to the 
UNIBUS; however, Appendix F provides the additional information 
needed to write a driver for a device attached to the MASSBUS. 


STRUCTURE OF THIS DOCUMENT 


This manual is organized into two parts. The first part consists of 
the following chapters, which introduce VAX/VMS device drivers and 
those aspects of the VAX-1l processor and the VAX/VMS system that are 
essential to drivers: 


e Chapter 1 introduces the main concepts associated with drivers 
on VAX/VMS. 


e Chapter 2 describes an example of a line printer driver 
handling a data transfer. 


e Chapter 3 discusses synchronization mechanisms: interrupt 
priority levels, fork processes and fork queues, and resource 
wait queues. 


e Chapter 4 discusses UNIBUS considerations for direct memory 
access (DMA) transfers. 


e Chapter 5 provides an overview of I/O processing and discusses 
the interaction between device drivers and VAX/VMS. 


X1 


The second part of this document is a series of “how to" chapters that 
provide a sample approach to coding a device driver: 


Chapter 6 contains a template for coding a device driver. 


Chapter 7 details the macros that drivers invoke to create 
necessary tables. 


Chapter 8 describes the coding of function decision routines. 
Chapter 9 describes the coding of a start I/O routine. 


Chapter 10 describes the UNIBUS considerations for a start I/O 
routine. 


Chapter 11 describes the coding of an interrupt service 
routine. 


Chapter 12 describes the coding of I/O completion and device 
timeout routines. 


Chapter 13 describes the coding of unit and controller 
initialization routines, I/O cancellation routines, and 
error-logging routines. 


Chapter 14 describes the loading of a driver into the system. 


Chapter 15 describes the debugging tool XDELTA that you can 
use to debug a device driver. 


Appendix A describes the I/0 data base in detail. This is’ an 
important appendix for the programmer of a device driver. 


Appendix B describes the VAX/VMS macros that drivers’ can 
invoke. 


Appendix C describes the VAX/VMS routines that device drivers 
can call. 


Appendix D contains a sample driver for an analog-to-digital 
converter. 


Appendix E contains a sample driver for two connected DRIl1ls. 


Appendix F contains information needed to write a device 
driver for a device attached to the MASSBUS. 


The glossary at the end of this manual defines I/O-related and 
driver-related terms. | 


ASSOCIATED DOCUMENTS 


This document has the following prerequisites: 


Manual 





I/O-related portions of the VAX/VMS System Services Reference 


Xil 


e The appendix on naming conventions in the VAX-1ll Guide_ to 
Creating Modular Library Procedures 





e VAX/VMS I/0 User's Guide 
The following documents are associated with this manual: 
@e VAX/VMS System Dump Analyzer Reference Manual 


ei 


e VAX/VMS System Manager's Guide 
CONVENTIONS USED IN THIS DOCUMENT 
This manual describes code transfer operations in three ways. 


1. The phrase "issues a system service call" implies the use of 
a CALL instruction. 


2. The phrase “calls a routine" implies the use of a JSB or’ BSB 
instruction. 


3. The phrase "transfers control to" implies the use of a_ BRB, 
BRW, or JMP instruction. 


X1i1 


SUMMARY OF TECHNICAL CHANGES 


Please refer to the section on system programming in the VAX/VMS 
Release Notes (Version 2.0) for a detailed description of the 


technical changes to VAX/VMS that affect device drivers. 


X1V 


PART | 


CHAPTER 1 


INTRODUCTION TO DEVICE DRIVERS 


Under the VAX/VMS operating system, a device driver is a eset of 
routines and tables that the system uses to process an I/O request for 
a particular device type. In order to understand how drivers are used 


by the VAX/VMS system, you must become familiar with the following 
basic concepts: 


e Asynchronous nature of a device driver 
e Fork processes 
e Process and interrupt context 
e Device dependence and device independence 
e I/0 data base 
e Synchronization mechanisms 
The beginning sections of this chapter describe the concepts’ listed 


above. The later sections describe the more concrete aspects of 
drivers, such as the actual functions they perform. 


1.1 ASYNCHRONOUS NATURE OF A DEVICE DRIVER 


Normally, a device driver module consists of the following routines 
and tables: 


e An I/O preprocessing routine or routines” that validate 
device-specific parameters of an I/O request, format data, 


allocate system buffers, and lock pages in memory 


e A start I/O routine that activates the device 


e An interrupt service routine that responds to interrupts from 
the device unit 


e An error recovery routine that retries I/0 operations and 
performs other error handling 


e An error-logging routine that writes the contents of device 
registers and other data into an error buffer for the system 


e A cancel I/O routine that prevents further processing of an 
I/O request 


INTRODUCTION TO DEVICE DRIVERS 


e An initialization routine that readies a device or controller 
for operation when the system is bootstrapped or during power 
failure recovery 


e A driver prologue table that describes the driver and _ the 


device type to the VAX/VMS procedure that loads drivers into 
the system 


e A driver dispatch table that lists the entry point addresses 
of standard driver routines and records the size of diagnostic 
and error-logging buffers for the device type 


e A function decision table that lists all valid function codes 
for the device and lists the addresses of I/O preprocessing 
routines associated with each valid function 


With a few exceptions, which are noted in Chapter 7, the order of the 
various routines and tables within the driver module is not important. 


Using the driver tables and other information maintained by the driver 
and the operating system, the system determines which routines to 
activate and when they should be activated, as illustrated in Figure 
1-1. For example, when a user process issues a Queue I/O Request 
system service, the system service calls various driver routines’ to 
perform preprocesSing of the I/O request. Likewise, if a user process 
issues a Cancel I/O on Channel system service, the system service 
activates the driver's cancel I/O routine. 


1/0 
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START 
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INITIALIZATION 









DEVICE 
UNIT 
INITIALIZATION 


SERVICE 
DEVICE 
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DEVICE 
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OPERATION 
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Figure 1-1 VAX/VMS Calls to Driver Routines 


INTRODUCTION TO DEVICE DRIVERS 


A device driver does not run from start to. end. The system calls 
driver routines and suspends and resumes them; the central processor 
interrupts and reactivates driver routines. Because little sequential 
processing of driver. code occurs, VAX/VMS muSt assume the 
responsibility for synchronizing the execution of the various driver 
routines and synchronizing the execution of all drivers in the system. 
The VAX/VMS operating system synchronizes driver execution using fork 
processes, interrupt priority levels, fork queues, and resource wait 
queues, described in the following sections. 


1.2 FORK PROCESSES 


A fork process 1S a process that is created dynamically and has 
minimal context. Fork processes execute entirely within the system 
address space. The VAX/VMS operating system creates and schedules a 
fork process by constructing a specialized control block called a fork 
block, inserting the fork block in a fork queue, and requesting a 
software interrupt. Fork queues and fork process dispatching are 
described further in Section 1.6.2. 


A driver fork process has the following context: 
e Three general registers 
e Program counter (PC) 


e A unit control block in the I/O data hase that describes’ the 
target device of the I/O request 


The unit control block also contains the driver's fork block. Section 
1.5 describes the unit control block and other control blocks in the 
I/O data base. 


Like other processes, fork processes can be suspended and interrupted. 
VAX/VMS places a driver fork process in a wait state when the process 
requests an unavailable resource, for example, a controller data 
channel. The processor interrupts a fork process when the processor 
receives a request for an interrupt at a higher priority level. 


Driver fork processes execute at raised interrupt priority levels’ to 
minimize the number of interruptions. They can raise the priority 
level to 31 to block all other interrupts, if necessary. 


The system automatically saves registers’ for interrupted fork 
processes and restores these registers when the process is 
reactivated. The operating system does not swap fork processes 
because the fork block and all data about the fork process reside in 
nonpaged system memory. 


1.3 PROCESS CONTEXT AND INTERRUPT CONTEXT 


Because a device driver consists of a number of routines that are 
activated by VAX/VMS, the operating system for the most part 
determines the context in which the routines execute. AS an example, 
consider the following write request that occurs without error: 


e A user process executing in user mode issues a write Queue I/0 
Request system service. 


e The Queue I/O Request system service gains control in user 
process context but in kernel mode. 


1-3 
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The system service uses the driver's function decision table 
to call the appropriate preprocessing routines. These 
routines, called FDT routines, execute in full process context 
in kernel mode. 


When preprocesSing is complete, a VAX/VMS' routine creates a 
fork process to execute the driver's start I/O routine in 
kernel mode. 


The start I/O routine activates the device unit and suspends 
itself. At this point, VAX/VMS suspends the fork process 
executing the start I/O routine and saves’ sufficient context 
to reactivate the start I/O routine at the point of 
suspension. 


When the device completes the data transfer, it issues an 
interrupt. The interrupt causes the system to activate the 
driver's interrupt service routine. 


The interrupt service routine executes to handle the device 
interrupt. It then causes the start I/O routine to resume in 
interrupt context. 


The start I/O routine regains control in interrupt context but 
almost immediately issues a request to the operating system to 
transform its context to that of a fork process. This action 
dismisses the interrupt. 


When reactivated in fork process context, the start I/0 
routine performs device-specific I/0 completion and passes 
control to the system for additional I/O postprocessing. 


VAX/VMS I/O postprocessing performs processing at a_ software 
interrupt priority level and then issues a kernel mode AST for 
the user process requesting I/O. 


When the kernel mode AST is’ delivered, the AST routine 
executes in full process context at kernel mode to deliver 
data and status to the process. If the original request 
specified a user mode AST, the kernel mode AST queues it. 


When the user process gainS control, the user's AST routine 
executes in full process context in user mode. 


It is essential, however, that the various driver routines not attempt 
to exceed the limitations of the context in which they execute. The 


majority 


of driver routines execute in fork process context. 


Execution context is mentioned throughout this document. 


1.4 DEVICE DEPENDENCE AND DEVICE INDEPENDENCE 


The VAX/VMS approach to I/0 is that the operating system should 


perform 


as much of the processing of an I/O request as possible and 


that drivers should restrict themselves to the device-specific aspects 


of I/0 


processing. To accomplish this, the VAX/VMS operating system 


provides drivers with the following services: 


The Queue I/O Request system service preprocesses an I/0 
request by performing those functions’ and checks that are 
common to all devices; for example, it validates the 
arguments in the I/O request that are not device specific. 
This type of preprocessing is called device-independent 
preprocessing. 
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e The VAX/VMS operating system includes a number of routines 
that drivers can call to perform I/O preprocessing, allocate 
and deallocate resources, and synchronize driver execution. 


@e VAX/VMS I/0 postprocessing performs the device-independent I/0 
postprocessing for all I/O requests. 


Thus, drivers can leave the device-independent I/O processing to’ the 
operating system and concentrate on the device-dependent aspects of a 
device unit; that is, those aspects that vary from device type to 
device type. In addition, drivers can call the VAX/VMS system to 
perform many functions that are device specific but common to several 
devices. 


1.5 THE I/O DATA BASE 


Because a driver and the operating system cooperate to process an I/O 
request, they must have a common I/O data base. Under VAX/VMS, the 
I/O data base consists of three main parts: 


e Driver tables that allow the system to load drivers, validate 
device functions, and call drivers at their entry points 


e Control blocks that describe every bus adapter, every device 
type, every device unit, every controller, and every logical 
path (channel) from a process to a device 


e I/0 request packets that define individual requests for I/0 
activity 


The three driver tables are defined in every driver. Section 1.l 
lists these tables. Appendix A describes each of the control blocks 
and the I/O request packet in detail. The use of this information in 
driver processing is discussed throughout this manual. 


Figure 1-2 illustrates some of the interrelationships among VAX/VMS 
I/O routines, the I/O data base, and a device driver. 
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Figure 1-2 The I/O Data Base 
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1.5.1 Control Blocks in the I/O Data Base 
Control blocks in the I/O data hase permit access to and _ describe 
peripheral hardware. The VAX/VMS operating system creates these 
control blocks either at system start-up or at the time a user-written 
driver is loaded into the system. Drivers refer to some or all of the 
following control blocks: 

e Device data block (DDB) 

@e Unit control block (UCB) 

e Channel request block (CRB) 

e Interrupt data block (IDB) 

e Adapter control block (ADP) 


e Channel control block (CCB) 


1.5.1.1 Device Data Block - A device data block contains information 
common to all devices of the same type that are connected to a 


particular controller. It records the generic device name 
concatenated with the controller designator, and the driver name and 
location for those devices. In addition, the device data block 


contains a pointer to the first unit control block for the device 
units attached to the controller. 


1.5.1.2 Unit Control Block - The system defines a unit control block 
for each device attached to the system. A unit control block defines 
the characteristics and current state of an individual device unit. 
In addition, it contains the fork block used by the unit's device 
driver and the listhead for the queue of pending I/O request’ packets 
for the unit. BecauSe drivers execute as fork processes that are 
created for each I/O operation on a unit, the unit control blocks) are 
the focal point of the I/O data base. When a driver is suspended or 
interrupted, the UCB fork block holds the driver's context. 


1.5.1.3 Channel Request Block - The operating system creates a 
channel request block for each controller. A channel request block 
defines the current state of the controller and lists the devices 
waiting for the controller's data channel. In addition, it contains 
the code that dispatches a device interrupt to the interrupt service 
routine for that unit's driver. 


1.5.1.4 Interrupt Data Block - The system creates an interrupt data 
block for each controller. An interrupt data block lists the device 
units associated with a controller and points to the unit control 
block of the device unit that the controller is currently servicing. 
In addition, an interrupt data block points to device registers’ and 
the controller's UNIBUS adapter. 
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1.5.1.5 Adapter Control Block - An adapter control block defines’ the 
characteristics and current state of a UNIBUS or MASSBUS adapter. An 
adapter control block for the UNIBUS adapter contains the queues~ and 
allocation bit maps necessary to allocate adapter resources. VAX/VMS 
provides routines that drivers can call to interface with their UNIBUS 
adapter. 


1.5.1.6 Channel Control Block - A channel is a logical path between a 
process and the unit control block of a specific device unit. The 
Channel control block describes this path. Each process owns a number 


of channel control blocks. When a-_ process issues the Assign I/0 
Channel system service, the system writes a description of the 
assigned device to the channel control block. Unlike the data 


structures mentioned earlier, a channel control block is not located 
in nonpaged system space, but in the process's control region (Pl 
space). 


1.5.2 I/0 Request Packets 


The third part of the I/O data base is a list of I/O request packets 
(IRPS). When a process requests I/O activity, the operating system 
constructs a packet of data, called an I/0 request packet, that 
describes the I/O request in standard form. 


The I/O request packet contains fields into which the system and 
driver I/O preprocessing routines can write information, such as 
device-dependent parameters specified in the call to the Queue I/O 
Request syStem service. Later, the system sends the I/O request 
packet to the device driver start I/O routine. The driver start I/0 
routine uses’ the packet as its source of detailed instructions about 
the operation to be performed. The packet includes buffer addresses, 
a pointer to the target device, I/0 function code, and further 
pointers to the I/O data base. 


1.6 SYNCHRONIZATION 


The VAX/VMS operating system uSes hardware and software interrupt 
priority levels (IPLS) with their associated interrupts, fork queues, 
and resource wait queues to synchronize the execution of all drivers 
within the system and to synchronize execution of various routines 
within a driver. 


1.6.1 Interrupt Priority Levels 


The VAX-11l processor defines 32 interrupt priority levels (0 through 
31). The higher numbered IPLsS are reserved for hardware interrupts, 
for example, device interrupts. The operating system uses the lower 
numbered IPLS. A higher IPL always takes precedence over a lower IPL. 
The VAX-11/780 Hardware Handbook describes the VAX-11 processor's use 
of IPLs. The following IPLS are of particular interest to drivers: 





e Hardware device IPLS (20 through 23); driver interrupt 
service routines execute at these IPLs. 


e Driver fork processing IPLs (8 through 11); driver’ fork 
processes execute at these IPLs. 
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e 1/0 completion IPL (IPL 4); VAX/VMS gains control to begin 
its device-independent I/O postprocessing at this IPL. 


e AST delivery IPL (IPL 2); VAX/VMS uses this IPL to coordinate 
the delivery of an AST to aeuser process. The Queue I/O 
Request system service also executes at this IPL. 


When the processor grants a device interrupt while a driver fork 
process is executing, the processor and the VAX/VMS’ interrupt 
dispatcher save the driver fork process context. The processor pushes 
the PC and PSL at the time of the interrupt onto the interrupt stack. 
In addition, the interrupt dispatcher saves RO through R5 on the 
stack. 


The interrupt service routine activated as a result of the interrupt 
follows conventions to preserve all other context of the interrupted 
process, as follows: 


e Uses only RO through R5 
e Cleans up the stack after use 


When the interrupt has been serviced, the driver interrupt service 
routine restores RO through R5 from the stack. The processor restores 
the previous PC and PSL of the interrupted code. The driver’ fork 
process then resumes execution without any awareness of the 
interruption. | 


1.6.2 Fork Queues 


When an interrupt service routine completes the handling of a device 
interrupt, it transfers control to the driver to complete 
device-dependent procesSing of the I/O request. When the driver 
regains control, it is executing at device IPL. Almost immediately, 
the driver should lower IPL to driver fork IPL so that it does not 
block other device interrupts. A driver lowers IPL by invoking a 
VAX/VMS macro that creates a fork process to execute at a lower IPL. 


Each driver fork IPL has an associated fork queue. A VAX/VMS- macro 
queues the driver's fork block in the fork queve that corresponds to 
the driver's fork IPL and issues a software interrupt request for that 
TPL When the software interrupt iS granted, the VAX/VMS fork 
dispatcher dequeues fork blocks from the driver fork queues”) and 
reactivates the driver at the point following the macro invocation. 


1.6.3 Resource Wait Queues 
Drivers compete for the following shared resources: 
e Central processor 


e UNIBUS adapter mapping registers, if the device is a DMA 
device 


e UNIBUS adapter buffered data paths, if the device is a DMA 
device 


e The controller data channel if the device is attached to a 
multiunit controller 
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When a driver fork process needs an unavailable resource, VAX/VMS 
resource management routines perform the following steps: 
e Save fork process context in the device's UCB fork block 


e Insert the address of the UCB fork block in a reSource wait 
queue 


e Suspend the driver fork process 
When another driver fork process frees the necessary resource, the 
VAX/VMS resource management routines take the following steps to 
reactivate the next driver fork process: 

@e Remove the next UCB fork block from the resource wait queue 

@e Restore fork process context into the registers 


e Reactivate the suspended driver fork process 


The VAX/VMS reSource management routines allow the driver fork process 
to be unaware of its suspension and reactivation. 


1.7 FUNCTIONS OF A DEVICE DRIVER 


A VAX/VMS device driver controls I/O operations on a peripheral device 
by performing the following functions: 


e Defines the peripheral device for the rest of VAX/VMS 
e Defines the driver for the system procedure that loads’ the 
driver into system virtual address space and that creates the 


driver's associated data structures 


e Readies the device and/or its controller for operation at 
system start-up and during recovery from a power failure 


e Performs device-dependent I/O preprocessing 


e Translates programmed requests for I/O operations into 
device-specific commands 


e Activates the device 

e Responds to hardware interrupts generated by the device 
e Responds to device timeout conditions 

e Responds to requests to cancel I/O on the device 

e Reports device errors to an error-logging program 


e Returns status from the device to the process that requested 
the I/O operation 


The driver prologue table, described in Section 7.1, performs’ the 
first two functions listed above. Driver routines perform the 
remaining functions. 
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1.7.1 Initialization Routines 


Most device controllers and device units require initialization when 
the VAX/VMS driver loading procedure loads the driver into memory and 
during recovery from a power failure. The amount and type of 
initialization varies from device type to device type. Section 13.1 
provides additional initialization information. 


1.7.2 FDT Routines 


Every driver contains a function decision table (FDT) that indicates 
the I/O preprocessing routines that are to be executed for various 
functions on the device. When a user process issues a Queue I/O 
Request system service, the system service uses the I/O function code 
specified in the request to select one or more FDT routines’ for 
execution. FDT routines perform such functions as allocating buffers, 
locking pages in memory, and validating device-dependent parameters 
(Pl through P6) of the I/O request. 


The driver contains FDT routines that are device-dependent. VAX/VMS 
provides additional FDT routines’ that perform processing common to 
many I/O functions, aS described in Section 8.5. It is advisable _ for 
drivers to use FDT routines supplied by the operating system whenever 
possible. 


Because FDT routines are called by the Queue I/O Request’ system 
service, they execute in full uSer process context. As a result, FDT 
routines have access to user-specified buffers located in the process 
address space; these buffers are not available to driver routines 
executing in fork context. 


1.7.3 Start I/O Routine 


The start I/O routine executes in a driver fork process to perform the 
following device-dependent functions: 


e Translate the I/O function code into a device-specific command 


e Transfer the details of the request from the I/O request 
packet to the device's unit control block 


e Obtain access to the controller if it is a multiunit 
controller 


@e Obtain the necessary UNIBUS reSources if the transfer is 
direct memory access (DMA) 


e Modify the device registers to activate the device 


e Perform device-dependent I/0 postprocessing after the transfer 
occurs 


The start I/O routine may be forced to wait for the controller or 
UNIBUS reSources to become available. In either case, VAX/VMS 
suspends the routine and reactivates it when the resources are free. 
Section 1.6.3 describes the context that VAX/VMS' saves’ for the 
suspended routine. 


After activating the device, the start I/O routine invokes the VAX/VMS 
wait for interrupt macro. The wait for interrupt macro suspends the 
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driver. The driver remains suspended until the driver's interrupt 
service routine handles the interrupt and returns control to the 
driver. At that point, the driver performs device-dependent I/0 
postprocessing and then transfers control to VAX/VMS for 
device-independent I/O postprocessing. 


1.7.4 Interrupt Service Routine 


When a device interrupt occurs, VAX/VMS transfers control to the 
device driver's interrupt service routine in interrupt context. The 
interrupt service routine determines whether the interrupt was 
expected or not and takes the appropriate action. Then the interrupt 
service routine resumes the driver for I/O postprocessing. 


1.7.5 Device Timeout Handler 


As the result of an error condition or a device's being offline, it is 
possible for a device to fail to complete a transfer in a reasonable 
period of time. This condition is called device timeout. When a 
Start I/0 routine invokes the wait for interrupt macro, it specifies 
the time interval in which the device can complete a transfer without 
timing out and the name of a timeout handler that the system is to 
invoke in the case of a timeout. This information is recorded in the 
device's unit control block. 


Once every second, the VAX/VMS system timer checks all devices in the 
system for device timeout. When it locates a device that has timed 
out, it calls the timeout handler. Like the driver's I/0 completion 
function, the timeout handler gains control in interrupt context. 


1.7.6 Cancel I/O Routine 


VAX/VMS provides the Cancel I/O on Channel system service that user 
processes can call to cancel I/O requests. The Cancel I/O on Channel 
system service, in turn, calls the driver's cancel I/0 routine. 
VAX/VMS also calls the driver's cancel I/O routine when the device's 
reference count goes to zero; that is, when all users that assigned 
channels to the device have deassigned them. 


1.7.7 Error-logging Routine 


The driver's error-logging routine fills an error log buffer with 
information about the error, for example, register contents. VAX/VMS 
provides a routine that drivers can call to allocate an error log 
buffer and transfer control to the register dump routine. 


1.8 AN EXAMPLE OF A UNIBUS I/0 REQUEST 
Figure 1-3 illustrates how the VAX/VMS operating system and the device 


driver process a user process request for a read I/O operation on a 
DMA UNIBUS device. 
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Figure 1-3 Processing a Sample I/O Operation 


The processing of the sample I/O request illustrated in 


occurs in the following steps: 


Figure 1-3 


e A process requests I/O operation. A user process”) requests 
data from the device by issuing either of the following: 


- A VAX~11 RMS get record function call (which results 
in a Queue I/O request) 
- A Queue I/O Request system service 
The user process specifies the target device, a read function 


code, and the address of a buffer in which the data 1s to he 


read. 


e The operating system performs I/O preprocessing. The Queue 
I/O Request system service validates the request and locates 
I/O data base control blocks that describe the device and its 
driver. The system service also allocates and initializes an 
I/O packet to contain a description of the I/O request. The 
System service then calls a read function routine in the 
driver. 


e The driver performs I/O preprocessing. The driver function 
decision table routine verifies that the user buffer resides 
in virtual memory pages that can be modified by the requesting 
process, locks the buffer pages in memory, and adds details of 
the I/O operation to the I/O request packet. The read FDT 
routine then calls the operating system to_ send the I/0 
request packet to the driver. 


e VAX/VMS creates a driver fork process. A VAX/VMS~ routine 
creates a fork process in which the device driver can execute. 
The routine activates the driver fork process by transferring 
control to the driver's start I/O routine. 


e The driver readies the UNIBUS adapter. For DMA transfers, the 
driver fork process calls VAX/VMS routines that control the 
UNIBUS adapter hardware to map UNIBUS addresses into physical 
addresses for the transfer. 

e The driver activates the device. The fork process activates 

the device by setting bits in device registers. 


e The driver waits for an interrupt. A VAX/VMS-~ routine’ saves 
the context of the driver fork process and relinquishes the 
processor until an interrupt occurs. 
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e The device requests an interrupt. When the data transfer is 
complete, the device requests a hardware interrupt that causes 
the system to dispatch to the driver's interrupt service 
routine. 


e The driver services the interrupt. The driver's interrupt 
service routine handles the interrupt and reactivates the 
driver, which reads device registers’ to obtain status 
information about the transfer. 


e The operating system inserts the driver in a fork queue. The 
driver requests that the process be reactivated at a lower 
software interrupt priority level. 


e The fork dispatcher reactivates the driver fork process. When 
processor priority permits, the VAX/VMS' fork dispatcher 
reactivates the driver as a fork process. 


e The driver completes the I/0 operation. The driver fork 
process completes device-dependent I/O processing of the I/0 
request and returns the I/O status to VAX/VMS. 


e VAX/VMS completes the I/0 operation. The VAX/VMS I/O 
postprocessing routines copy the I/O status into process 
address space and/or general registers and return control to 
the uSer process. 


Of the thirteen steps listed above, only four describe driver I/0 
preprocessing and driver fork processing. The VAX/VMS I/O support 
routines perform all I/O processing common to many or all “I/O 
requests. Even in device driver routines, driver coding is simplified 
by the use of VAX/VMS' routines that handle device-independent 
functions. 


The 13-step example condenses and simplifies the processing of an I/0 
operation by ignoring such issues as the following: 


e Association of a device with a _ process; that is, device 
assignment 


e Simultaneous I/O requests for one device 
e Hardware interrupt priority levels 


e Driver competition for shared system and UNIBUS' adapter 
resources 


e Driver competition for I/0 activity through a multiunit 
controller 


e Driver recovery from device errors or power failure 
Later chapters discuss each of these issues in relation to device 
drivers. 


1.9 THE UNIBUS 


On a VAX-1l1 system, the internal processor bus (that is, the 
synchronous back plane interconnect) connects the central processor to 
memory. The internal processor bus also connects the UNIBUS adapter 
and MASSBUS adapter (MBA) to memory and to the central processor. 
Peripheral devices attach to either the UNIBUS, for UNIBUS devices, or 
the MASSBUS, for MASSBUS devices, as illustrated in Figure 1-4, 
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Figure 1-4 VAX~-11 Hardware Configuration 


The VAX-11/780 Hardware Handbook describes the hardware components 
diagrammed in Figure 1-4. 


VAX/VMS provides device drivers for a number of standard devices 
Supported by DIGITAL. These devices are connected to either the 
MASSBUS or the UNIBUS. 


Nonstandard devices, that is, cuStomer-supplied devices, normally are 
connected to the UNIBUS, but can also be attached to the MASSBUS or to 
the DR32 high bandwidth bus. DIGITAL supplies a device driver and an 
application library for the DR32 bus; see the chapter on the DR32 
Interface Driver in the VAX/VMS I/0 User's Guide for further 
ee en eee AS MIE a i ee Acai 


To activate a direct memory access (DMA) transfer on the UNIBUS, a 
driver must first obtain mapping registers, and, optionally, a 
buffered data path. The driver calls VAX/VMS routines that interface 
with the UNIBUS adapter to allocate these resources on behalf of the 
driver. 


The direct data path maps each UNIBUS transfer to an SBI transfer. 
For each UNIBUS transfer, there is one SBI transfer. Each SBI 
operation transfers a single word or byte of data depending on_ the 
device. A buffered data path, on the other hand, allows a quadword of 
data to be assembled and transferred in one SBI operation. Up to 
eight UNIBUS transfers occur for each SBI transfer. 
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Drivers performing nonDMA transfers are generally not concerned with 
UNIBUS adapter operation.1l 


1.10 PROGRAMMED I/O AND DIRECT MEMORY ACCESS I/0 
Devices transfer data using one of the following methods: 
@e Programmed I/0 
e Direct memory access (DMA) transfers 


Devices that perform programmed I/O transfer data as single words or 
bytes uSing device registers. After each transfer completes, the 
device notifies the central processor. 


Devices that perform DMA transfers do not require the _ central 
processor so frequently. Once the driver activates the device, the 
device can transfer a large amount of data without requesting an 
interrupt after each of the smaller amounts. Normally, the driver of 
a DMA device allocates a UNIBUS buffered data path and UNIBUS-) map 
registers for I/O transfers. 


1.11 BUFFERED I/O AND DIRECT I/0 


Drivers can perform I/O transfers using either of the following 
methods: 


e Buffered I/0 
e Direct I/0 


Buffered I/O allows data to be buffered in system address space. When 
the transfer is complete, the data is transferred to the user 
process's buffer. The driver can refer to the buffer in system space 
using system virtual addresses. Often, a driver uses buffered I/O for 
devices that perform programmed I/O, for example, line printers’ and 
card readers. 


Direct I/O allows data to he placed directly in the user’. process's 
buffer. The driver must lock the pages containing the buffer in 
physical memory and refer to them uSing page frame numbers’ (PFNs). 
Normally, a driver uses direct I/0 and a buffered data path for 
devices that perform DMA transfers. 


The trade-off between buffered I/O and direct I/O is the time required 
to move the data into the user's buffer versus the time required to 
lock the buffer pages in memory. Chapter 8 provides additional 
information. 


1. Instead of creating a complete device driver for a nonDMA device, 
you can connect the process to the device interrupt vector to program 
the device from a user process. For a description of how and when to 
connect to an interrupt vector, consult the VAX/VMS Real-Time User's 
Guide. 


INTRODUCTION TO DEVICE DRIVERS 


1.12 LOADABLE DRIVERS 


The VAX/VMS operating system provides a procedure that allows a 
Suitably privileged user to load drivers into a running VAX/VMS 
system. The SYSGEN utility, described in full in the VAX/VMS_ System 
Manager's Guide, supports commands that invoke the driver loading 
procedure: 


e LOAD -- to load a driver into the system 


e CONNECT -- to create the I/O data base for additional devices 
of the same type 


e RELOAD -- to load a previously loaded driver 


The driver loading procedure uses information provided in the LOAD 
command and information contained in driver tables to load the driver 
into virtual memory and create the associated data base. The driver 
prologue table, which must be the first generated code in the driver 
module, contains the information that the loading procedure needs. 
Specifically, the driver prologue table contains the following: 


e Address of the end of the driver; the loading procedure uses 
this to determine the size of the driver 


e Driver loader flags that indicate whether the device needs a 
System page table entry and whether the driver can be reloaded 


e The size of the unit control block 
e Address of a routine to call if the driver is reloaded 
e Name of the device driver module 


The driver prologue table can be followed by two lists of fields that 
require initialization: 


e I/0 data base fields to be initialized the first time the 
driver is loaded 


e Fields to be initialized every time the driver is reloaded, 
that is, without an intervening bootstrap of the system 


With the information provided in the driver prologue table and the two 
lists of fields, the driver loading procedure can both load and reload 
drivers and perform the initialization that is appropriate to either 
Situation. 


CHAPTER 2 


DISCUSSION OF A LINE PRINTER QUEUE I/O REQUEST 


The LP1l is a buffered line printer. A user process can request’ the 
following functions for this printer: 


e Write data to the line printer 
e Read the line printer's device characteristics 
e Alter the line printer's device characteristics 


This chapter describes the following aspects of line printer I/0 
processing: 


e The portions of the VAX/VMS device driver for an LPl1l line 
printer that are used in Servicing a write request 


e The VAX/VMS components with which the driver interacts’ to 
process the write request 


The LPll was selected for this discussion because it is ae simple 
driver but still illustrates many driver principles. Although the 
LP1l is usually spooled, for purposes of this discussion, assume that 
it is not spooled. 


The first-time reader of this document may not understand all of the 
points made in this chapter; however, the chapter should provide some 
insight into driver flow and I/0 processiiig. 


Figure 2-1 illustrates the flow of execution through VAX/VMS~ routines 
and the line printer driver to satisfy this I/O request. 


The double-sided boxes in Figure 2-1 indicate processing performed by 
driver subroutines. Boxes shown above the dotted line indicate 
processing in the context of the user process. Boxes below the dotted 
line indicate processing in fork or interrupt context. 
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Figure 2-1 A Line Printer Write Function 


2.1 DRIVER CODE FOR THE LP1ll WRITE FUNCTION 


The VAX/VMS device driver for an LP1l line printer implements a write 
function using the following parts of the driver: 


An FDT routine that reformats the user~supplied data 


A driver start I/O routine that writes data to the device 
print buffer until the printer enters a busy state to print 
the contents of the buffer 


Code that modifies a device register to enable interrupts from 
the line printer 
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e A driver interrupt service routine that returns control to the 
driver fork process after a hardware interrupt from the line 
printer 


e Code that returns I/O status to a VAX/VMS I/0 completion 
routine 


2.2 A USER PROCESS'S I/O REQUEST 


A user process writes a line to the printer by issuing a Queue _ I/O 
Request system service call that specifies the write virtual block 
function code, as follows: 


SQIO § CHAN = CHANNEL NUMBER,- 
- FUNC = #I0S WRITEVBLK,- 
EFN = #6,- _ 
IOSB = STATUS BLOCK,- 


Pl = BUFFER_ADDRESS,- 
P2 = #BUFFER_SIZE,- 
P4 = #°X30 


The parameters Pl, P2, and P4 are device-dependent parameters. 


2.3 I/O PREPROCESSING BY VAX/VMS 


When called, the Queue I/O Request system service first validates that 
the I/O request is correctly Specified; that is, the I/O request must 
meet the following criteria: 


e The location CHANNEL NUMBER must contain a channel number that 
serves as an index into the process I/O channel list. The 
process must have previously assigned the line printer device 
to this process channel using the Assign I/O Channel system 
service, 


During verification of the channel number, the Queue I/O 
Request system service obtains the address of the line printer 
driver's function decision table (FDT). Figure 2-2 
illustrates the chain of pointers from the channel index 
number to the FDT address. As a result of chaining through 
the I/O data base, the Queue I/0 Request system service also 
determines what device is the target of the request. 


e The line printer FDT must list IOS WRITEVBLK as aé_e valid 
function for the device. 


e The event flag number must be valid. 
e The process buffered I/O request quota must permit the Queue 
I/O Request system Service to perform a buffered I/O request 


without exceeding the process's quotas. 


e The process must have write access to the user-specified 
location to be used as an I/O status block. 
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Figure 2-2 Locating a Function Decision Table 


If all of the checks described above succeed, the Queue I/O Request 
system service creates an I/O request packet in nonpaged system 
address space. The service then writes all known details about’ the 
I/O request into the I/O request packet. 


If the target device for the I/O request is not file-structured, the 
Queue I/0 Request system service changes any virtual function code to 
its logical equivalent when it builds the I/O request packet. Thus, 
for a line printer device, IOS WRITEVBLK is translated to 
IO$ WRITELBLK. User-written drivers Should check that virtual 
Function codes have corresponding logical codes. 


2.4 I/O PREPROCESSING BY THE DRIVER 


Once it has validated the I/O request, the Queue I/O Request system 
service scans the function decision table for an entry that associates 
the IOS WRITELBLK function code with an FDT routine. The system 
service calls the routine, which in the case of the line printer 
driver is a device-specific routine located in the line printer device 
driver. 


The FDT routine confirms that the requesting process has read access 
to the buffer starting at BUFFER ADDRESS. Then, the FDT routine 
buffers data from the process address space into system address’ space 
in the following steps: 


e It calculates the length of the required system space buffer. 


e If the process byte count quota for buffered I/O (BYTCNT) 
permits, the routine allocates a buffer from system address 
space, stores the address of the buffer in the I/O request 
packet, and decreases the current process byte count quota. 
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e It then synchronizes with other possible subprocesses! to read 
and write fields of the line printer's unit control block. 


e It reads the description of the line printer's current’ line 
and page position from the device's unit control block. 


e It reformats the data from the process buffer into the system 
buffer, adding carriage control characters, as specified in 
the I/O request argument P4, before and after the data. 


Formatting includes such functions as the replacement of 
horizontal tabs with multiple spaces and the replacement of 
lowercase characters with uppercase characters. 


e It rewrites updated line and page positions into the device's 
UCB. This information indicates what the current location on 
the page being printed will be where the request completes. 


e Finally, the routine transfers control to a VAX/VMS~ routine 
that queues the I/O packet to the device driver. 


All of the I/O processing described to this point occurs in the 
context of the user's process. The user address space is mapped, and 
the processor's interrupt priority level (IPL) is still low enough to 
permit process scheduling and _ paging. Subsequent queuing of the 
transfer request to the driver and all resulting driver processing 
occur at higher interrupt priority levels that synchronize driver 
handling of the device, as described in Chapter 3. 


2.5 QUEUING THE I/O PACKET TO THE DRIVER 


Before queuing the I/O request packet to the proper driver, the 
VAX/VMS queuing routine raises the interrupt priority level to the 
driver fork level (UCBSB_ FIPL) Stored in the unit control block. 
Raising IPL to fork level synchronizes driver access to the unit 
control block. 


If the device is idle, that is, if the busy bit (UCBSV BSY) in the I/0 
Status word of the unit control block is clear, VAX/VMS can transfer 
control to the driver. The driver dispatch table contains the entry 
point to the driver's start I/O routine. To find the proper entry 
point, the queuing routine chains through the I/O data base to the 
driver dispatch table, as follows: 


UCB —3™ DDB —™ DDT —~ Entry point to start I/O routine 


If the device unit is busy with another transfer, VAX/VMS inserts’ the 
T/O request packet in a queue of packets waiting for the unit. The 
unit control block contains the head of the queue. The packet's 
position in the queue depends on the scheduling priority of the 
process issuing the request. 


1. For example, if a process allocates a printer, it is possible for 
the process and any of its subprocesses to isSue write requests to the 
printer concurrently. 
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2.6 DRIVER DEVICE ACTIVATION 


The LPll line printer controller accepts data into a device data 
buffer until the print buffer is full or the driver writes a carriage 
control character into the print buffer. When either event occurs, 
the line printer sets a busy bit in the device's control/status 
register. Then a device driver sets the interrupt enable bit in the 
device's control/status register and waits for the printer’ to 
interrupt. When the line printer requests a hardware interrupt, the 
driver can resume putting characters in the print buffer. 


The line printer driver routine writes to the line printer data buffer 
according to the following sequence: 


1. The driver locates the LPll device registers using a chain of 
pointers starting at the device's unit control block (UCB). 


UCB —™ CRB —, IDB —~»m CSR address 


In contrast to many other devices, such as disks, the LPll 
line printer does not Share a controller with other devices. 
Therefore, no arbitration for ownership of the controller is 
required. The CSR address is always the address of the line 
printer control/status register, and all other device 
registers are at fixed offsets from this address. 


2. The driver examines the device's control/status register to 
see if the device is ready to accept characters. 


3. If the device is ready, the driver writes a byte of data into 
the line printer data buffer and decreases the count of bytes 
to transfer. It then repeats step 2. 


4. If the device iS not ready, that is, if the device's internal 
buffer is full, the driver raises IPL to 31 to block out all 
interrupts and sets the interrupt enable bit in the device's 
control/status register. 


After enabling interrupts, the driver invokes a VAX/VMS wait 


for interrupt macro to suspend driver processing until the 
line printer requests an interrupt or the device times out. 


2.7 WAITING FOR A DEVICE INTERRUPT 


The VAX/VMS wait for interrupt routine suspends the driver by 
performing the following functions: 


e Saving driver context (R3, R4, and the address of the next 
instruction in the driver) in the device's unit control block 


@e Calculating the time at which the device will time out 
e Setting bits in the device's unit control block to indicate 
that the driver expects a device interrupt within a specified 


time period 


VAX/VMS then drops IPL back to driver fork level and returns’ control 
to the caller of the driver's start I/O routine. 
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The driver remains in a suspended state until one of two events 
occurs: 


e The line printer requests a hardware interrupt. 


e VAX/VMS reports a device timeout because the line printer did 
not request a hardware interrupt within a specified period of 
time. 


Normally, the LPll prints the contents of its data buffer and requests 
the interrupt. 


2.8 INTERRUPT HANDLING 


When the LP1ll line printer requests a hardware interrupt, the UNIBUS 
adapter interrupt service routine gains control. The service routine 
reads the device vector from a UNIBUS adapter register and passes’ the 
interrupt to the LPll driver interrupt service routine. 


The driver's interrupt service routine restores control to the driver, 
as follows: 


e Confirms that the interrupt was expected by examining bits in 
the device's unit control block 


e Restores the saved registers (R3 and R4) from the device's 
unit control block 


e Restores the address of the unit control block in R5 


e Transfers control to the driver PC address stored in the 
device's unit control block 


Rather than execute in interrupt context, the reactivated driver 
routine calls a VAX/VMS' routine to create a driver fork process. 
VAX/VMS again suspends driver processing by performing the following 
steps: 


e Saving driver context (R3, R4, and the driver PC address) in 
the device's unit control block 


e Inserting the UCB address in the appropriate fork queue 
The driver suspension allows the operating system to reschedule driver 
processing at a lower IPL. A VAX/VMS fork dispatcher reactivates the 
driver when IPL drops to driver fork level. 
After creating the fork process, the system returns control to the 
driver's interrupt service routine. The service routine performs the 
following steps: 


e Restores registers saved at the time of the device interrupt 


e Dismisses the interrupt 
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2.9 I/O COMPLETION PROCESSING BY THE DRIVER 


When the VAX/VMS fork dispatcher reactivates the driver fork process, 
the driver code continues transferring characters into the line 
printer data buffer until the transfer is complete. The driver code 
performs the following steps to transfer characters: 


e It obtains the number of characters left to transfer from the 
unit control block. 


e It transfers characters until the LPll again prints its data 
buffer or all characters have been transferred. 


e When all characters have been transferred, the driver code 
branches to driver I/O completion code. 


The driver's I/O completion code stores the following information in 
RO: 


e A success Status code 
e The number of bytes transferred 


Then, the driver code transfers control to VAX/VMS to complete the I/O 
request. 


2.10 I/O COMPLETION PROCESSING BY THE VAX/VMS SYSTEM 


The operating system inserts the I/O request packet into an I/0 
postprocessing queue. If another I/O request packet is in the wait 
queue for the device unit, VAX/VMS dequeues that packet and calls’ the 
driver start I/O routine to process it. 


When IPL drops to IPLS IOPOST, the processor grants the I/O 
postprocessing interrupt request. The I/O postprocessing dispatcher 
dequeues the packet for the line printer I/O request and performs’ the 
following steps: 


e it increases the use count of the process's buffered I/0 
requests since the current operation is complete. The uSe 
count iS maintained for accounting purposes. 


e It deallocates the system buffer used for the reformatted user 
data. 


e It increases the process's current byte count quota. 


e It sets an event flag to indicate that the I/0 operation is 
complete. 


e It queues a kernel mode AST routine that deallocates the I/0 
request packet and stores I/0 status into the user's I/O 
Status block. 


The user process examines the event flag or issues a Wait for Single 
Event Flag system service call to determine that the I/O operation is 
complete. 


CHAPTER 3 


SYNCHRONIZATION OF I/0 REQUEST PROCESSING 


The VAX/VMS operating system uses three mechanisms to synchronize I/O 
processing: 


e Hardware interrupt priority levels and interrupt service 
routines 


e Driver fork processes, fork blocks, and fork queues 
e Resource wait queues 


When programming a driver, you muSt obServe the VAX/VMS-~ conventions 
that govern the usSe of interrupt priority levels and fork processes. 
The VAX/VMS routines that grant resources to drivers enforce the use 
of resource wait queues. 


3.1 INTERRUPT PRIORITY LEVELS 


The VAX-11 processor defines 32 levels of hardware priorities, called 
interrupt priority levels (IPLS). IPL 0 has the lowest priority, and 
IPL 31 has the highest. Interrupts can be requested either by 
software (software interrupts) or by. the hardware (hardware 
interrupts). The system uses the various interrupt priority levels as 
follows: 


e User mode software runs at IPL 0. 


e Operating system routines and driver fork processes’ request 
software interrupts at IPLs 1 through 15. 


e Devices and error conditions generate hardware interrupts at 
IPLs 16 through 3l. 


Many IPLS have an interrupt service routine associated with them. The 
processor responds to both software and hardware interrupts by 
transferring control to the appropriate interrupt Service routine. 
The interrupt service routine processes the interrupt and, when 
finished, dismisses the interrupt with an REI instruction. 


3.1.1 IPLs Defined by VAX/VMS 


Table 3-1 describes the uses that VAX/VMS defines for IPLs 0. through 
Ls 
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Table 3-1 
IPLs Defined by VAX/VMS 
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User mode software 









Reserved 


2 IPL$ ASTDEL AST delivery interrupt service routine 

3 IPL$ SCHED Scheduler interrupt service routine 

4 IPL$S IOPOST I/O postprocessing interrupt service routine 
5 IPL$ XDELTA XDELTA interrupt service routine 

6 IPL$ QUEUEAST Fork level processing for queuing ASTs 

7 IPL$ SYNCH System data base access and software timer 


IPL$ TIMER interrupt service routine 


Fork level for driver execution 


12 Reserved 
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3.1.2 IPLs Defined for the Hardware 


Hardware interrupt levels are used for device interrupts (IPLS 20 
through 23) and urgent conditions including power failure and serious 
errors such as a machine’ check. The VAX-11/780 Hardware Handbook 
provides additional information about hardware interrupt levels. 





3.1.3 Interrupt Service Routines 


The VAX/VMS operating system uses interrupt service routines that gain 
control at the preset IPLS described above. Using preset IPLs 
guarantees that interrupts are processed according to the following 
priorities: 


e Device interrupts (highest priority) 

e Device driver fork processes 

e I/0 postprocessing 

e Process scheduling 

e AST delivery (lowest priority) 
For example, VAX/VMS completes the processing of an I/O request’ by 
placing the I/O request packet in the I/O postprocessing queue and 
requesting an interrupt at the I/O postprocessing IPL (IPL 4). When 
the interrupt priority level drops below 4, the processor grants the 


software interrupt by transferring control to the I/O postprocessing 
service routine. 


SYNCHRONIZATION OF I/0 REQUEST PROCESSING 


Interrupt service routines run in a reduced context. The stack iS a 


special stack used only during interrupt processing; it is the 
interrupt stack. Of the register set, usually only RO through R5 are 
saved. The interrupt service routine must restore these registers 


before it returns from an interrupt. If the service routine uses any 
other registers, the routine must save the registers before use and 
restore them after use. Using registers other than RO through R5 is 
not recommended. 


When an interrupt occurs, the system transfers control to the driver 
interrupt service routine with IPL set to the hardware device 
interrupt level. Since code executing at IPLsS 20 through 23 blocks 
most other hardware interrupts and all software interrupts, driver 
code lowers its IPL as Soon as possible. 


The operating system allows the creation of a fork process so that a 
driver can continue execution without blocking other device 
interrupts. Section 3.2 discusses fork processes. 


3.1.4 Raising IPL 


Code running in kernel mode can raise its IPL to lock out ~ context 
switching and block interrupts. VAX/VMS software interrupt service 
routines perform some of their processing at IPLs higher than the IPL 
at which the routines gain control. For example, the scheduler is an 
interrupt service routine that gains control at IPL 3; however, it 
raises IPL to 7 to read and modify the system data base. I/O drivers 
typically raise IPL to check for a power failure, send a message to a 
mailbox, and sometimes to access device registers. Driver code should 
not raise IPL for more than a few instructions because So ponng blocks 
all interrupts at lower IPLs. 


3.1.5 Lowering IPL 


Once an interrupt service routine has received the interrupt, it 
transfers control to the main flow of driver code. At this point, the 
driver is executing in the context of an interrupt service routine and 
at device IPL. 


When a driver gains control, it may execute a few instructions at’ the 
high IPL; however, almost immediately a driver lowers IPL to fork 
IPL. A driver lowers IPL by invoking the VAX/VMS macro that creates 
fork processes, IOFORK. As a result of invoking IOFORK, VAX/VMS 
performs the following functions for the driver: 


e Consults the device's unit control block to determine fork IPL 
for the driver 


e Creates a driver bari process and queues it for execution at 
the appropriate IPL 


e Requests a software interrupt at that IPL 


When the queued driver fork process is reactivated, it executes at the 
lower fork IPL. Section 3.2 describes fork process dispatching in 
greater detail. 


Driver fork processes also can modify IPL by invoking certain VAX/VMS 
macros; Section 3.1.11 describes these macros. Normally, a driver 
uses these macros to raise IPL before initiating a transfer. 
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3.1.6 Servicing Hardware Interrupts 


VAX-11 peripheral devices request interrupts at IPLsS 20 through 23. 
When a device requests an interrupt at one of these IPLs and the 
processor is executing at a lower IPL, the processor performs’ the 
following: 


e Grants the interrupt 


e Transfers control to an interrupt service routine for the 
device 


If the processor is executing at a higher or equal IPL, the interrupt 
remains pending. 


Transferring control to the interrupt service routine requires’ that 
the processor first transfer control to the interrupt dispatcher for 
the adapter (MASSBUS or UNIBUS) to which the device is attached. The 
interrupt dispatcher is itself an interrupt service routine. The 
dispatcher locates the channel request block (CRB) for the device and 
transfers control to the dispatching field. The channel request block 
contains a JSB instruction that, in turn, transfers control to_ the 
driver's interrupt service routine. When the interrupt service 
routine issues an REI instruction, the code executing prior to the 
interrupt resumes unless interrupts occurred at levels between that of 
the executing interrupt service routine and the interrupted code. 


Figure 3-1 illustrates the steps performed by the hardware and VAX/VMS 
to transfer control to a driver interrupt service routine after a 
UNIBUS device interrupt. 


3.1.7 Transferring Control to the Driver Fork Process 


When a device driver receives an expected interrupt from a device, the 
driver interrupt service routine executes in the context of an 
interrupt; it is not executing in driver fork process context at that 
point. Interrupt context has the following characteristics: 


e IPL is elevated to the level at which the device requests 
hardware interrupts. 


e The stack is the interrupt stack. 

e The top of the stack contains a pointer to the address of the 
controller's interrupt data block (IDB), which contains the 
address of the control/status register. 


e The stack also contains saved RO through R5 and the PC and PSL 
of the interrupted code. 
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Figure 3-1 Servicing Hardware Interrupts 
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The interrupt occurs either because the device haS completed an I/0 
operation or because an error occurred during the I/O operation. 
Driver interrupt service routineS generally determine whether to 
service the interrupt by examining the I/O data base. If the unit 
control block for the device that currently owns the controller 
indicates that the interrupt is expected, the service routine takes 
the following steps to transfer control to the driver's start I/0 
routine: 


e Loads the UCB address into R5 


e Restores the contents of two registers (R3 and R4) from the 
UCB fork block 


e Returns control to the saved PC in that fork block 


The driver may need to execute a few instructions in the context of 


the interrupt. For example, the driver may copy device status 
information from device registers into the device's unit control 
block. After executing these instructions at device IPL, the driver 


completes the I/O processing at a lower priority by creating a_e fork 
process, as described in Section 3.2. 


3.1.8 IPL Use During I/O Processing 
I/O processing occurs mainly at the following IPLs: 
e IPLS ASTDEL (IPL 2) 
e IPL$ IOPOST (IPL 4) 
e Driver fork processing IPLS (IPLs 8 through 11) 
e Hardware device IPLs (IPLs 20 through 23) 


e IPLS POWER (IPL 31) 


3.1.8.1 IPL$ ASTDEL (IPL 2) - IPLS ASTDEL blocks the delivery of 
asynchronous system traps (ASTs). When a system service for which an 
AST was specified completes, the system service queues the AST and 
causeS a software interrupt to be requested at IPLS ASTDEL. The AST 
delivery interrupt service routine gains control when IPL drops’ below 
IPL$S ASTDEL. It delivers the AST to the process that is currently 
scheduled. 


Any driver routine that allocates or deallocates dynamic system pool 
space while running in the context of a process (for example, an FDT 
routine) must do so at an IPL of IPLS ASTDEL or higher. The VAX/VMS 
allocation routine records the address of the allocated system memory 
in a register. If an AST that aborts the process were to occur, the 
allocated memory would be lost from the pool. To block ASTs, I/0 
preprocessing from the time that the Queue I/O Request system service 
allocates an I/O request packet through the execution of the last FDT 
routine occurs at IPLsS no lower than IPLS ASTDEL. 


A process cannot incur page faults when IPL is above IPLS ASTDEL. Any 
code that executes at a higher IPL must refer only to nonpaged virtual 
memory or pages that have been locked in virtual memory. A fatal 
bugcheck occurs if a page fault is incurred above IPLS ASTDEL. 
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In addition, some I/O postprocessing occurs in a kernel mode AST 
service routine that also executes at IPLS ASTDEL. Kernel mode ASTs, 
running in the context of a process whose I/O completed, write status 
information into I/0 status blocks, copy buffered input into process 
space, and deallocate system buffers. 


3.1.8.2 IPLS$ _IOPOST (IPL 4) - I/O postprocessing includes all I/0 
completion processing that can occur without reference to the device's 
unit control block and, thus, can occur at an IPL lower than driver 
fork IPL. To request I/0 postprocessing, drivers call a VAX/VMS 
routine that inserts I/O request packets in the postprocessing queue 
and requests a software interrupt at IPLS IOPOST. 


I/O postprocessing runs at an IPL higher than IPL$ SCHED so that all 
pending I/0 completion processing is finished before the scheduler 
looks for a new process to Schedule. Whether a process iS awaiting 
I/O completion affects its ability to execute. Since I/0 
postprocessing queues ASTS to processes, the scheduler may 
preferentially reschedule a waiting process because of a pending AST 
to the process. 


The VAX/VMS operating system performs I/O postprocessing in the IPL 4 
interrupt service routine. This routine adjusts process quota use, 
queues a kernel mode AST to write status and data into the process's 
address space, and deallocates system memory. 


3.1.8.3 Driver Fork Processing (IPLS 8 through 11) - Driver fork 
processing occurs at an IPL in the range 8 through 11 depending on the 
contents of the unit control block field UCBSB FIPL. UCBSB_FIPL 
contains a value that is used as that device's fork IPL. All driver 
routines, except for most FDT routines, execute at driver fork IPL or 
higher. Usually driver routines should not read or alter fields of 
the unit control block unless IPL is at fork level or higher. 


A driver must never lower IPL below the IPL of the interrupt’ that 
cauSed the driver to be reentered unless the driver does so by 
creating a fork process at the lower IPL. 


All devices on a single UNIBUS adapter share the same fork IPL if they 
actively compete for Shared UNIBUS adapter resources such as map 
registers and data paths. 


3.1.8.4 Hardware Device Interrupts - The UCBSB DIPL field in the 
device's unit control block contains an IPL value at which the device 
requests hardware interrupts. This IPL is in the range 20 through 23 
because device interrupts usually need to interrupt most user and 
VAX/VMS software functions. IPLs 20 through 23 correspond to UNIBUS 
bus request (BR) levels 4 through 7. Device drivers sometimes raise 
IPL to UCBSB DIPL or higher before reading and writing certain device 
registers. —_ 


3.1.8.5 IPL$ POWER - The highest IPL, IPLS POWER, locks out all other 
interrupts. Many VAX/VMS routines and drivers raise IPL to IPL$ POWER 
to execute code sequences that cannot tolerate interruption. For 
example, much of system initialization occurs at IPLS$ POWER. 
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When a device driver needs to execute a series of instructions without 
interruption, the driver raises IPL to IPL$ POWER. The driver never 
should remain at IPLS$ POWER for more than a few instructions. The 
most common instance of a driver's raising IPL to IPLS POWER is to 
determine whether a power failure has occurred between the time that 
the driver writes set-up data into device registers and the time that 
the driver starts the device by writing into the device control 
register. 


3.1.9 Additional IPLs 


In addition to the IPLsS described above, VAX/VMS' defines the 
following: 


@ IPLS SCHED (IPL 3); never used by drivers 
@ IPLS QUEUEAST (IPL 6); very seldom used by drivers 


® IPL$ SYNCH and IPLS$ TIMER (IPL 7); very seldom used by 
drivers 


e IPLS MAILBOX (IPL 11); very seldom used by drivers 


For debugging purposes, the VAX/VMS operating system defines’ the 
priority level IPLS XDELTA (IPL 5); it is described in Section 
3.1.9.5. 7 


3.1.9.1 IPL$ SCHED - When the system wishes to reschedule processes, a 
VAX/VMS routine requests a software interrupt at IPLS SCHED. The 
scheduler interrupt service routine gains control at this IPL. 


If a process raises IPL to or above IPLS SCHED, the scheduler cannot 
reschedule the processor. The process runs until an interrupt occurs 
at a higher IPL or the process reduces IPL below IPLS SCHED. 


3.1.9.2 IPL$ QUEUEAST - IPLS QUEUEAST is a fork level IPL. That is, 
the interrupt service routine for IPL$ QUEUEAST is the fork dispatcher 
that dequeues fork blocks and restores control to fork processes 
needing to execute at IPLS$ QUEUEAST. 


To queue an AST, a driver creates a fork process at IPLS$ QUEUEAST. 
When the fork dispatcher restores control to the fork process, the 
process can raise IPL to IPLS SYNCH and queue the AST. 


A driver that wishes to gain access to the system data base for any 
reason can also create ae fork process at IPL$ QUEUEAST. The fork 
dispatcher restores control to the driver at IPLS QUEUEAST, and_ the 
driver can then raise IPL to IPLS SYNCH (a nonfork IPL) to gain access 
to the system data base. _ 


3.1.9.3 IPL$ SYNCH and IPL$ TIMER - IPLS SYNCH is the system data base 
synchronization level. When a VAX/VMS subroutine or a driver needs to 
modify or read a dynamic portion of the system data base, the routine 
always executes at IPLS SYNCH to ensure that the data base does not 
change due to some interrupt service routine or process. action. For 
example, the driver loading procedure invoked by the SYSGEN utility 
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raises IPL to IPLS$S SYNCH before adding control blocks to the I/O data 
base. ~~ 


A timer queue interrupt service routine fields interrupts requested at 
IPL$ TIMER, which is also IPL 7. The hardware clock interrupt service 
routine requests a software timer interrupt at IPLS TIMER when the 
current process has exceeded its processor time quantum or when the 
first entry in the timer queue is due. The timer interrupt service 
routine dequeues the first timer queue entry and takes appropriate 
action. 


3.1.9.4 IPL$ MAILBOX - When a VAX/VMS or driver routine writes into a 
mailbox, IPL must be at IPLS MAILBOX to prevent other writers from 
modifying incomplete data in the mailbox, or readers from reading 
invalid data. 


IPL$ MAILBOX is the highest fork level; drivers can raise IPL to 
IPLS MAILBOX and write into a mailbox. 


3.1.9.5 IPL$ XDELTA - To stop the operating system for debugging 
purposes, you can halt the operating system from the console terminal 
and request a software interrupt at IPLS XDELTA. The processor must 
be executing below IPL 5 for the interrupt to have an effect. Chapter 
15 describes the XDELTA debugging program. 


3.1.10 Overview of IPL Use 


Figure 3-2 illustrates the normal IPL flow during the processing of an 
I/O request. 


The user program, executing at IPL 0, issues a Queue I/0 Request 
system service call. I/O processing by the system service and FDT 
routines occurs mostly at IPLS ASTDEL. Very rarely, an FDT routine 
raises IPL to driver fork level to read or modify the device's unit 
control block. 


The start I/O routine executes as a fork process at fork IPL, but may 
raise to device interrupt IPL or IPLS POWER for short periods of time. 
After the driver fork process activates the device, the driver calls a 
VAX/VMS routine that saves the driver fork context, suspends driver 
fork processing, and restores IPL to a previous level. 


Figure 3-3 illustrates the completion of the I/O request from. the 
point of the device interrupt to the delivery of ASTs to the user 
program. The device interrupts at a device IPL (in the range 20 
through 23). VAX/VMS transfers control to the appropriate driver 
interrupt service routine. The service routine reactivates the driver 
fork process with IPL still at hardware device IPL. 


The fork process briefly examines or saves the contents of device 
registers, but Soon requests that VAX/VMS insert ae fork block 
describing its context into one of the fork queues for driver fork 
IPLs (8 through 11). When the driver fork process regains control at 
driver fork IPL, the process analyzes the success of the I/O operation 
and writes status into RO and Rl. Then, still at driver fork IPL, 
VAX/VMS inserts the I/O request packet into the I/0 postprocessing 
queue and starts the next I/O request. 
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Figure 3-2 IPL Conventions During I/O Processing 
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Figure 3-3 IPL Conventions During I/O Completion 
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The I/O postprocessing routine adjustS process quota usage _ and 
deallocates system buffers for write functions at IPLS IOPOST. The 
routine also calls another VAX/VMS' routine that raises IPL to 
IPLS SYNCH to queue a kernel mode AST to the process that issued the 
original QIO request. The AST routine executes at IPLS$ ASTDEL, and 
may queue a user AST routine that eventually executes at an IPL of O. 
I/O postprocessing continues at IPLS IOPOST until all entries in the 
postprocessing queue have been serviced. 


3.1.11 Modifying IPL in Driver Code 


The interrupt priority level at which driver code executes changes as 
a result of either of the following events: 


e The driver's calling a VAX/VMS routine that raises or lowers 
IPL 


e The driver's invoking a VAX/VMS macro to request explicitly a 
change in IPL 


Subsequent chapters of this manual discuss the VAX/VMS-~ routines” that 
change IPL; discussions include their expectation of IPL at entry and 
their IPL setting at exit. The sections that follow describe the 
macros that drivers can call to change IPL: 


e SETIPL 
e DSBINT 
@ ENBINT 
e SOFTINT 


3.1.11.1 Set Interrupt Priority Level Macro - The Set Interrupt 
Priority Level (SETIPL) macro moves the specified IPL into the IPL 
processor register. 


Format 
SETIPL [ipl] 
ipl 
The interrupt priority level. If no priority level is specified, 


the macro moves the value 31 into the IPL register. Setting IPL 
to 31 blocks all interrupts. 


3.1.11.2 Disable Interrupts Macro - The Disable Interrupts (DSBINT) 
macro saves the current IPL in the specified destination and moves the 
specified IPL into the IPL processor register. Procedures invoke this 
macro to raise IPL. 

Format 


DSBINT [ipl] [,dst] 


31 
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ipl 
The interrupt priority level. The macro saves the current IPL. on 
the top of the stack (default) or in the specified destination 
and moves the specified IPL into the IPL register. If IPL is not 
specified, the macro moves the value 31 into the IPL processor 
register; this blocks all interrupts. 

dst 


The location in which the current IPL is to be’ Saved. If this 
argument is not specified, the current IPL is stored on the top 
of the stack by default. 


3.1.11.3 Enable Interrupts Macro - The Enable [Interrupts (ENBINT) 
macro restores an IPL value to the IPL processor register. Procedures 
invoke this macro to lower IPL to a previously saved level. If an 
interrupt is pending at an intermediate IPL (that is, one lower than 
the current IPL but higher than the specified IPL), restoring IPL 
causes immediate interruption of the current procedure. 


Format 
ENBINT [src] 


sre 
The location containing the IPL to be restored. If this argument 
is not specified, the macro moves the IPL value contained on the 
top of the stack into the IPL register. 


3.1.11.4 Software Interrupt Macro - The Software Interrupt (SOFTINT) 
macro moves the specified IPL into the software interrupt request 
processor regiSter to request a software interrupt. If the processor 
is executing at a low IPL (for example, IPL 0) and detects a software 
interrupt request at a higher IPL (1 through 15), the processor 
immediately transfers control to a software interrupt service routine 
for the appropriate IPL. If the processor is executing at or above 
the specified IPL, the processor does not transfer control to the 
software interrupt service routine until IPL drops below the specified 
IPL. 


Format 
SOFTINT ipl 


ipl 
The interrupt priority level at which the software interrupt is 
being requested. 


3.2 FORK BLOCKS AND FORK DISPATCHING 


Device driver routines that activate a device and complete an I/O 
operation after a device interrupt execute for relatively short 
periods of time. Execution may be suspended to wait for a device 
interrupt or shared resources. To ensure that the resulting context 
Switching is fast, VAX/VMS forces driver routines to execute in a very 
minimal fork process context consisting of a device UCB, called a fork 
block, and a few registers. 
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Driver fork processes are created in either of the following 
situations: : 


e Once the preprocessing of an I/O packet has been performed, a 
VAX/VMS routine creates a fork process to execute the driver's 
Start I/O routine. If the driver is already busy, the VAX/VMS 
routine queues the I/O packet for the driver to process later. 


e Either the driver's interrupt service routine or the driver 
postprocessing routine creates a fork process’ to perform 
device-dependent I/O postprocessing. 


When the system creates a driver fork process to execute the start I/O 
routine, the newly created fork process can execute immediately 
because the I/O packet has been preprocessed by the Queue I/O Request 
system service and driver FDT routines, and the device is idle. 


When the driver interrupt service routine or the driver postprocessing 
routine creates a driver fork process, it does so to lower the IPL of 
the driver code. Either the service routine or the driver invokes the 
VAX/VMS macro IOFORK. IOFORK saves the context needed for the driver 
to execute as a fork process, inserts the driver's UCB fork block in 
the fork queue for the driver's IPL, and requests a software interrupt 
for that IPL. 


3.2.1 Interrupt Service Routine for Fork Dispatching 


One interrupt service routine handles all fork process dispatching. 
When the processor grants an interrupt at fork IPL, the’ fork 
dispatcher saves RO through R5 on the stack and processes the _ fork 
queue that corresponds to the IPL of the interrupt. To do so, it 
removes an entry from the fork queue, restores the fork process 
context, and reactivates the suspended fork process. When that fork 
process completes, the dispatcher regains control, removes the next 
entry, if any, from the queue, restores its fork process context, and 
reactivates it. This sequence repeats until the fork queue is empty. 
When the queue is empty, the fork dispatcher restores RO through R5 
from the stack and dismisses the interrupt with an REI instruction. 


Figure 3-4 illustrates the fork queue structure. 


A newly activated driver fork process executes under the following 
constraints: 


e It cannot refer to the address space of the process initiating 
the I/O request. 


e It can use only RO through R5— freely; it must save other 
registers before use and restore them after use. Use of 
registers other than RO through R5 is strongly discouraged. 


e It must clean up the stack after use; the stack must be in 
its original state when the fork process relinquishes control 
to any VAX/VMS routine. 


e It must execute at IPLS between driver fork level and 
IPL$_ POWER; it must not lower IPL below driver fork level 
except by creating a fork process at a lower IPL. 


e When it returns control to the fork dispatcher, IPL must be 
the same as it was when the driver fork process was activated. 
The driver returns control to the fork dispatcher by invoking 
the wait for interrupt macro or the request complete macro. 
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Figure 3-4 Fork Dispatching Data Structure 


3.3 RESOURCE WAIT QUEUES 


The processing of an I/O request often requires shared system 
resources such aS memory and UNIBUS adapter map registers. The Queue 
I/O Request system service and driver fork processes call VAX/VMS 


routines to allocate and deallocate these resources. Since the 
resources are limited, I/O processing may be delayed until unavailable 
resources are released by other processes or drivers. Thus, 


Synchronization of access to these resources can have ae_e substantial 
impact on I/O request processing. 


For example, the Queue I/O Request system service calls a VAX/VMS 
routine to allocate nonpaged system space for an I/O request packet. 
If the nonpaged pool is empty, the routine calls another VAX/VMS 
routine to save the process context and change the process state to 
resource wait mode (also called miscellaneous wait, or MWAIT). 
Process states and the resources’ for which processes can wait are 
described in the VAX/VMS Summary Description and Glossary. As a 
result of waiting, th process is a candidate to be swapped out of 
memory. When nonpaged pool becomes available, the scheduler 
reschedules the process. 





During driver fork process execution at raised IPLs, driver context is 
very small. At any point, the driver can obtain all details about an 
I/O request by referring to the I/O data base. The driver needs’7 only 
the address of the device unit control block which is the key to the 
rest of the data base. Therefore, VAX/VMS routines that control 
driver resources, such as UBA map registers, use driver fork blocks 
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and resource wait queues to save minimal driver context. Each entry 
in a queue consists of the following items: 


e The address of the UCB, which is also the contents of R5 in 
the driver fork process; the UCB also contains the driver 
fork block 


e R3, and normally R4, from the fork process 
e A PC for the waiting fork process 


When the awaited resource becomes available, the routine controlling 
the resource performs the following steps: 


e Restores the UCB address to R5 

e Restores the saved registers R3 and R4 

e Grants the resource 

e Transfers control to the saved driver return PC address 


Because the VAX/VMS routine that controls a particular resource places 
the driver in a wait state when the driver requests an unavailable 
resource, drivers are unaware of being suspended and subsequently 
resumed. Drivers must not leave anything on the stack when calling a 
routine that may suspend the driver. 


3.3.1 Competing for a Controller Data Channel 


A controller data channel is a VAX/VMS synchronization mechanism that 
guarantees for multiunit controllers that one unit uses the controller 
at a time. A device driver fork process can read and write a device's 
registers whenever the device unit owns the controller data channel. 


Devices that share a multiunit controller, such as disk units, own the 
controller data channel only when a VAX/VMS~ routine assigns the 
channel to the unit's driver fork process. In contrast, a single 
device unit on a controller always owns the controller data channel. 
Therefore, if VAX/VMS transfers control to such a driver's start I/0 
routine, the driver can immediately address the device registers 
without first obtaining the controller data channel. 


An LP11 line printer device, such as the one discussed in Chapter 2, 
has a dedicated (Single-unit) controller attached to the UNIBUS. When 
VAX/VMS finds the device idle and creates a line printer driver fork 
process to write data to the line printer data buffer, the controller 
data channel is guaranteed not to be busy. Because the controller 
data channel is not busy, the line printer start I/O routine can 
execute the following simple sequence of events: 


e Retrieve the virtual address of the data to be written and the 
number of bytes to transfer from the device's unit control 
block 


e Retrieve the virtual address of the device's control/status 
register from the interrupt data block 


SYNCHRONIZATION OF I/O REQUEST PROCESSING 


- @ Calculate the address of the line printer's data buffer 
register by adding a constant offset to the control/status 
register address 


e Write data one byte at a time to the line printer's data 
buffer until all bytes of data have been written 


In contrast, a device unit on a multiunit controller must compete for 
the controller data channel with other devices) attached to that 
controller. 


An RK611 controller, for example, controls as many as eight RKO0O6/RK07 
devices. The disk driver fork process must gain control of the 
controller data channel before starting an I/O operation on the unit 
associated with the fork process. The disk driver's start I/O routine 
uses the following sequence to start a seek operation on an _ RKO?7 
device: 


e The start I/O routine requests the controller data channel by 
invoking a VAX/VMS channel arbitration routine. 


e The VAX/VMS routine tests the CRB mask field to determine 
whether the controller data channel is available. 


e If the channel is available, the VAX/VMS routine allocates the 
channel to the driver fork process and returns the address of 
the device control/status register to the fork process. 


If the channel is busy, the VAX/VMS routine saves’ the driver 
fork context in the UCB fork block and inserts the fork block 
address in the controller channel wait queue. 


@e When the driver fork process resumes execution, the process 
owns the controller channel. The fork process can then modify 
device registers to activate the device. 


e The driver's start I/O routine then requests VAX/VMS_~ to 
suspend driver processing in anticipation of an interrupt or 
timeout and to release the channel. 


e The VAX/VMS channel releasing routine assigns channel 
ownership to the next driver fork process in the channel wait 
queue, loads the control/status register address into a 
general register, and reactivates the suspended driver fork 
process. 


e The reactivated fork process continues execution as though the 
channel had been available in the first place. 


The VAX/VMS channel arbitration routines keep track of controller 
availability using a flag field in the channel request block. The 
driver fork process must always request and release the controller 
data channel by invoking these routines. Once the driver owns a 
controller data channel, the driver is free to read and modify device 
registers. 
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THE UNIBUS ADAPTER 


The UNIBUS adapter connects the UNIBUS, an asynchronous’ bidirectional 
bus, to the synchronous backplane interconnect (SBI). The adapter 
performs the following functions: 


e Arbitrates priority interrupts from UNIBUS devices 
e Delivers interrupts from UNIBUS devices to the processor 


e Allows drivers to gain access to UNIBUS device registers using 
system virtual addresses 


e Translates 18-bit UNIBUS addresses to 30-bit SBI byte 
addresses 


e Provides a data transfer path to randomly ordered physical SBI 
addresses, that is, to discontiguous pages 


e Provides buffered data transfer paths to consecutively 
increaSing physical SBI addresses 


e Permits byte-aligned buffers for UNIBUS devices’ requiring 
word-aligned buffer addresses 


Together the UNIBUS adapter and the SBI permit devices and device 
drivers to exchange data without much awareness of the intervening 
hardware. Because VAX/VMS routines handle the details of the 
adapter/SBI interface, most device drivers do not need to know the 
interface protocol. 


The critical responsibility of UNIBUS device drivers that actively 
compete for shared UNIBUS adapter resources is that they all execute 
at the same fork IPL. This IPL convention synchronizes access to the 
UNIBUS adapter data structures, 


In general, device drivers use the UNIBUS adapter for the following 
purposes: 


e Reading and writing device registers 


@e Mapping UNIBUS addresses to SBI addresses and vice versa _ for 
direct memory access (DMA) transfers 


e Buffering data transfers 


Drivers for UNIBUS devices that do not perform DMA transfers’ are 
unaware of the presence of the UNIBUS adapter. The UNIBUS adapter 
provides access to device registers using an address mapping scheme 
that is invisible to the driver. However, drivers that handle DMA 
transfers to and from UNIBUS devices must call VAX/VMS routines” that 
establish the appropriate mapping. 
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4.1 READING AND WRITING DEVICE REGISTERS 


Each I/0 controller or device directly attached to the UNIBUS has a 
set of control/status and data registers. These registers are 
assigned addresses in a portion of the physical address space called 
the UNIBUS address”~ space. Device drivers obtain device status and 
activate devices by reading and writing these registers. 


Generally, a device driver can regard the addresses of device 
registers as identical to all other virtual addresses. The driver can 
read and write data to the device register as though the device 
register were a location in memory. The driver must obey the 
restrictions on instructions described in Section 6.2. The UNIBUS 
adapter performs the actual mapping of virtual address to UNIBUS 
addresses that correspond to device registers. 


Before a driver for a multiunit controller can gain access to device 
registers, it must first obtain a controller channel, as described in 
Section 3.3.1. 


4.2 MAPPING UNIBUS AND SBI ADDRESSES FOR DMA TRANSFERS 


The UNIBUS address space consists of 256K bytes of memory, of which 8K 
bytes are reserved for device control registers. UNIBUS DMA devices 
read and write data from and to memory locations uSing 18-bit UNIBUS 
addresses. The UNIBUS adapter translates the 18-bit UNIBUS addresses 
into 30-bit SBI addresses. This translation allows the operating 
system, I/O drivers, and UNIBUS devices to access the same physical 
address space. 


The UNIBUS adapter provides 496 map registers to translate UNIBUS 
addresses to SBI addresses. Each map register represents one page of 
the UNIBUS address’ space. A 21-bit field in the map register 
identifies the SBI page frame number corresponding to the UNIBUS 
address that the map register represents. 


For example, VAX/VMS routines fill as many map registers with valid 
SBI page addresses as needed for a DMA transfer. A DMA UNIBUS device 
puts an address on the UNIBUS. The UNIBUS adapter receives’ the 
address and translates it using the following information: 


e The 9-bit UNIBUS page address field (bits 9 through 17 of the 
UNIBUS address) identifies the UBA map register. 


e The 21-bit SBI page frame number field (bits 0 through 20) in 
the map register identifies bits 27 through 7 of the SBI 
address. 


e UNIBUS address bits 2 through 8 map directly to bits 0 through 
6 of the SBI address. 


The resulting 28-bit SBI address locates the SBI longword that is’ the 
target of the transfer. The UNIBUS adapter identifies the byte 
addressed within the longword by interpreting the low-order two bits 
of the UNIBUS address. 


Figure 4-1 illustrates the UNIBUS to SBI address mapping. 
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Figure 4-1 UNIBUS to SBI Address Mapping 


Each UNIBUS adapter map register also contains a bit called the map 
register valid bit. The UNIBUS adapter tests this bit every time the 
map register is used. If the bit is not set, the UNIBUS adapter 
aborts the UNIBUS transfer. The valid bit is zero whenever the 
register is not mapped to an SBI address. 


4.2.1 UNIBUS Adapter Data Transfer Paths 


The UNIBUS adapter sends data through one of 16 data paths for UNIBUS 
devices performing DMA transfers. One data path, the direct data path 
(DDP), allows UNIBUS transfers to randomly ordered SBI addresses. The 
direct data path maps each UNIBUS transfer to an SBI transfer. Thus, 
a Single word or byte of data is transferred per SBI operation. 


The other 15 data paths, the buffered data paths (BDPs), allow 
sequential access devices on the UNIBUS to transfer to consecutively 
increasing addresses much faster than through the direct data _ path. 
The buffered data paths store data from the UNIBUS until a quadword of 
data has been assembled. Then the UNIBUS adapter begins an_ SBI 
transfer. 


Buffered data paths also allow a UNIBUS device to transfer randomly 
ordered, longword-aligned 32-bit data. The longword-aligned transfer 
mode is discussed in Section 4.2.1.5. 


When a UNIBUS device begins a DMA transfer by placing an address on 
the UNIBUS, the UNIBUS adapter map register not only performs address 
mapping but also provides the number of the data path to be used for 
the transfer. Each UNIBUS adapter map register contains a 4-bit field 
that describes the data path. Data path 0 is the direct data _ path, 
and data paths 1 through 15 are the buffered data paths. 
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The sequence below describes a UNIBUS device DMA transfer. 
e The UNIBUS device puts an address on the UNIBUS. 


e The UNIBUS adapter locates the UNIBUS adapter map register 
that corresponds to the UNIBUS address. 


e The UNIBUS adapter verifies that the map register has the map 
register valid bit set. 


e The UNIBUS adapter maps the UNIBUS address to an SBI _ page 
frame number. 


e The UNIBUS adapter extracts the number of the data path to be 
used for the transfer from the map register. 


e The data path translates the UNIBUS' function to an_ SBI 
function by reading the UNIBUS control lines. 


e Based on the UNIBUS function indicated by the UNIBUS' control 
lines, (DATI, DATIP, DATO, or DATOB), the UNIBUS adapter 
Starts appropriate UNIBUS and SBI operations to transfer data 
to or from the UNIBUS device. 


4.2.1.1 Direct Data Path - Since the direct data path performs an SBI 
transfer for every UNIBUS transfer, the data path can be used by more 
than one UNIBUS device at a time. The UNIBUS adapter arbitrates 
between devices that wish to use the direct data path simultaneously. 
The device driver is unaware of this UBA arbitration. 


The direct data path is slower than buffered data paths because each 
UNIBUS transfer cycle corresponds to an SBI cycle. Throughput is one 
word or byte transferred per SBI cycle, which iS approximately a .8 
megabyte per second maximum. The direct data path is also unable to 
transfer a word of data to an odd SBI address. Therefore, an FDT 
routine for a DMA device that uses the direct data path might check 
that the specified buffer is on a word boundary. 


UNIBUS devices that transfer data through the direct data path do_- so 
in order to perform the following functions: 


e Execute an interlock sequence to the SBI (DATIP~DATO/DATOB) 


e Transfer to randomly ordered addresses instead of 
consecutively increasing addresses 


e Mix read and write functions 


The direct data path is the simplest data path to program. Since the 
direct data path can be shared simultaneously by any number of I/0 
transfers, the device driver need not allocate that data path. Once 
the map registers are loaded, the device driver initiates the transfer 
by setting appropriate device control register bits. The programming 
sequence is as follows: 


@e Allocate a set of map registers. 


e Load the map registers with SBI mapping data and the data path 
number (0 for the direct data path). 
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e Set the valid bit in every map register. The map register 
adjacent to the last map register must have the valid bit 
cleared. 


e Load the starting address of the transfer in a device 
register. 


e Load the transfer byte or word count in a device register. 


e Set bits in the device control register to initiate the 
transfer. 


The operating system performs the first three steps above. The driver 
fork process simply calls VAX/VMS routines to allocate and load the 
map registers. 


4.2.1.2 Buffered Data Paths - In contrast to the direct data _ path, 
the 15 buffered data paths transfer data much more efficiently between 
the UNIBUS and the SBI by decoupling the UNIBUS transfer from the’ SBI 
transfer. Buffered data paths read or write 32 or 64 bits of data in 
a transfer, and buffer the unrequested portions of the data in UBA 
buffers. Thus, aS many as four Separate UNIBUS read functions can be 
accommodated with a Single SBI transfer. 


Advantages that buffered data paths offer to UNIBUS devices include 
the following: | 


e Fast DMA block transfers to or from consecutively increasing 
addresses (maximum 1.39 megabyte per second transfer rate) 


e Word-oriented block transfers that begin and end on an_e odd 
byte of SBI memory; note, however, that these transfers can 
be quite slow since the UNIBUS adapter may need to transfer 
two quadwords to complete a l-word transfer 


e 32-bit data transfers from random longword-aligned SBI 
addresses 


A buffered data path cannot be assigned to more than one active 
transfer at a time. When a driver fork process iS preparing to 
transfer data to or from a UNIBUS device on a buffered data path, the 
driver requests allocation of a free buffered data path and a set of 
UBA map registers. A VAX/VMS I/O routine writes the number of the 
data path into each of the assigned map registers. 


A UNIBUS device transfer over a buffered data path has the following 
restrictions: 


e The driver must request the UNIBUS adapter to purge the 
buffered data path after each block transfer (except for 
error-free longword-aligned transfers). 


e All addresses in a block transfer must be consecutively 
increasing addresses. 


e All transfers within a block must be of the same function type 
(DATI or DATO/DATOB). 


A buffered data path buffers data from the UNIBUS until a quadword of 
data has been transferred (except in longword-aligned transfer mode; 
see below). Then, the UNIBUS adapter transfers the contents of the 
buffer to the appropriate SBI address in a single SBI operation. The 
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procedure for a UNIBUS write operation that transfers a quadword of 
data to memory is broken into individual steps below. 


e The UNIBUS device transfers one word of data to the buffered 
data path. 


e The buffered data path stores the word of data and completes 
the UNIBUS cycle. 


e The buffered data path sets its buffer-not-empty (BNE) bit to 
indicate that the buffer contains valid data. 


e The UNIBUS device repeats the first three steps until the 
UNIBUS address is the last byte or word of a physical 
quadword. 


e When the UNIBUS device addresses the last byte or word in a 
physical quadword, the UBA recognizes a complete 
data-gathering cycle. 


e The buffered data path requests an SBI extended write function 
to write a quadword of data from the buffered data path to 
memory. 


e When the SBI transfer is complete, the buffered data path 
clears its BNE bit to indicate that the buffer no longer 
contains valid data. 


The procedure for a UNIBUS read function using a buffered data _ path 
includes a prefetch function. The prefetch automatically reads 
another quadword of data from the SBI after the contents of a buffered 
data path is transferred to the UNIBUS. The prefetch speeds up UNIBUS 
reads from SBI memory. The steps of a UNIBUS read function are listed 
below. 


e The UNIBUS device initiates a read operation from a buffered 
data path. 


e The buffered data path checks to see if its buffers contain 
valid data. 


e If the buffers do not contain valid data, the buffered data 
path initiates an SBI extended read function to fill the 
buffers with a quadword of data. The SBI gquadword transfer 
completes before the UNIBUS adapter begins a UNIBUS transfer. 


e The buffered data path transfers the requested bytes to the 
UNIBUS. Bytes of data that were not transferred to the UNIBUS 
remain in the buffer. 


e The buffered data path sets its BNE bit to indicate that the 
buffers contain valid data. 


e When the UNIBUS device empties the buffers of the buffered 
data path with a UNIBUS read function that accesses the last 
word of a quadword-aligned group, the buffered data path 
clears the BNE bit to indicate that the buffers no longer 
contain valid data. 


e The buffered data path then initiates an SBI extended read 
function to prefetch a quadword of data from SBI memory. 


e When the SBI transfer iS complete, the buffered data path sets 
the BNE bit to indicate that the buffers now contain valid 
data. 
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The prefetch may attempt to read data beyond the SBI page address 
mapped by the final map register. To avoid a read to memory that does . 
not exist, the VAX/VMS map register allocation’ routine always 
allocates one extra map register and clears its valid bit before 
initiating the transfer. When the UNIBUS adapter notices that the map 
register for the prefetch is invalid, the UNIBUS adapter simply aborts 
the prefetch without reporting an error. 


4.2.1.3 Byte Offset Data Transfers - The buffered data paths permit 
UNIBUS devices that are restricted to transferring integral words of 
data in word-aligned UNIBUS addresses to perform transfers to. SBI 
memory that begins and ends on an odd-byte address. A byte-offset bit 
in the map registers indicates byte-aligned data to the hardware. If 
the bit is set, the hardware increments SBI addresses. A VAX/VMS 
subroutine that loads map registers determines whether the data is 
word-or byte-aligned and sets the byte offset bit accordingly. 


4.2.1.4 Purging a Buffered Data Path - Since prefetches may read more 
data from SBI memory than the UNIBUS device wishes to read, driver 
fork processes must ask the UNIBUS adapter to purge the buffered data 
path when a transfer iS complete. In addition, a transfer from a 
device to the SBI can complete with some data (less than a quadword) 
left in the buffer. The driver must purge the data path to complete 
the transfer. 


The purge guarantees that the data is not transferred to the next user 
of the buffered data path. The driver fork process performs the purge 
by calling a standard VAX/VMS subroutine that: 


e Sets the BNE bit in the buffered data path register owned by 
the fork process. For a UNIBUS read function, the adapter 
Simply clears the bit set by the subroutine. For a UNIBUS 
write function, the adapter transfers any data left in the 
data path buffer to VAX-1l memory, then clears the bit. 


e Notifies the driver fork process of any error that occurs 
during the purge. 


The data path must be purged before the driver releases map registers 
or the buffered data path register. 


4.2.1.5 Longword-Aligned 32-Bit Random Access Mode - Another’ method 
of transferring data over a buffered data path is in longword-aligned 
32-bit random access mode. This mode permits a device that reads data 
from or writes data to SBI memory in longword-aligned and 
longword-multiples to use the buffered data path for random memory 
access. 


A longword-aligned transfer over a buffered data path is faster than a 
direct data path transfer and somewhat slower than a normal buffered 
data path transfer (maximum 1.17 megabyte per second transfer rate). 


This longword-aligned use of the buffered data path disables’ the 
prefetch and makes normal purging of the data path unnecessary. If, 
however, the I/O transfer aborts, the driver must purge the data path. 


To transfer data in the longword-aligned 32-bit 
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random access mode, 
sets the longword-access-enable bit 
loading the 


the function occurs as follows: 


initiates a read function on the 


clears the BNE bit in the assigned buffered 


data path. 
The UNIBUS adapter issues a read from SBI memory operation. 
The UNIBUS adapter stores the longword of data in the buffered 
data path and sets the BNE bit. 
The UNIBUS adapter initiates two UNIBUS read operations’ to 
transfer two words of data. 
When the two read operations are complete, the UBA clears’ the 
BNE bit. 

the function occurs as follows: 
The driver fork process initiates a write function on_ the 


UNIBUS device. 


The UNIBUS adapter 
data path. 


The UNIBUS adapter 
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operation is complete, the UNIBUS adapter 
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OVERVIEW OF I/O PROCESSING 


Under the VAX/VMS operating system, I/O processing occurs in three 
major phases: 


e I/0 request preprocessing 


e Device activation and subsequent handling of the device 
interrupt 


e I/0 postprocessing 


When a user process issues an I/0 request, the Queue I/O Request 
system service gains control. The system service coordinates the 
preprocessing of the I/O request. The last driver FDT routine called 
by the Queue I/O Request system service calls a VAX/VMS routine that 
creates a driver fork process to execute the driver's start I/0 
routine; this is the routine that activates the device. When the 
transfer completes, the device requests an interrupt that results in 
execution of the driver's interrupt service routine. This routine 
handles the interrupt and requests creation of a driver fork process 


to perform device-dependent I/O postprocessing. The driver fork 
process” then transfers control to the system to perform 
device-independent I/O postprocessing. Figure 5-1 illustrates the 


sequence of events. 


5.1 PREPROCESSING AN I/0 REQUEST 

The Queue I/O Request system service performs device-independent 
preprocessing of an I/O request and calls driver FDT routines to 
perform device-dependent preprocessing. To preprocess an I/O request, 
the Queue I/O Request system service takes the following steps: 


e Verifies that the requesting process has assigned a _ process 
I/O channel to the target device 


e Locates the device driver in the I/O data base 
e Validates the I/O function code 

e Checks process I/O request quotas 

e Validates the I/O status block 

e Allocates and sets up the I/O request packet 


e Calls driver FDT routines to perform device-dependent 
preprocessing 
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5.1.1 Process I/O Channel Assignment 


The first step in preprocessing an I/O request is to verify that the 
I/O request specifies a valid process I/O channel. The process I/0 
channel is an entry in a system-maintained process table _ that 
describes a path of reference from a process to a peripheral device 
unit. Before a program requests I/0 to a device, the program 
identifies the target device unit by issuing an Assign I/O Channel 
system service call. The Assign I/O Channel system service performs 
the following functions: 


e lLocates an unused entry in the table of process I/O channels 


e Creates a pointer to the device unit in the table entry for 
the channel 


e Returns a channel index number to the program 


When the program isSues an I/O request, the Queue I/O Request’ system 
service verifies that the channel number specified is associated with 
a device and locates the portion of the I/O data base that describes 
the device. Figure 5-2 illustrates the path from a process channel 
number to the device's unit control block. 


5.1.2 Locating a Device Driver in the I/O Data Base 


Using information in the unit control block, a driver can find other 
I/O data structures associated with the device, including the 
following: 


e Channel request blockt 
e Interrupt data block 


e Device data block 


5.1.2.1 Unit Control Block (UCB) - The process channel number 
indirectly points to the unit control block for the target device. 
The unit control block contains the first in a chain of pointers’ into 
the I/O data base. The pointer chain leads to the addresses of driver 
tables and routines in the driver that services the target device. 


A unit control block describing a device unit exists for each device 
in the system. The unit control block indicates the current state of 
the device unit by specifying such information as the following: 


e Whether the device is active 
e What I/O request is being processed 


e Where transfer buffers are located 


1. Channel request blocks (CRBs) and channel control blocks are_ two 
completely separate data structures. It is sometimes helpful to think 
of the channel request block as the "controller" request block because 
it describes the hardware controller. The channel control block, on 
the other hand, describes a logical path from a process to. an 
associated unit control block. 
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Since drivers run as fork processes and cannot use process’7 address 
Space to store additional context, drivers use the unit control block 
for temporary data storage during I/O processing. Chapter 7 describes 
how you can allocate additional UCB space for storing data or 
device-dependent driver context. 


The unit control block also holds the context of a driver fork process 
when VAX/VMS I/0 routines suspend the fork process to wait for an 
asynchronous event such as a device interrupt. 
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Figure 5-2 Locating the Target Device 
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5.1.2.2 Channel Request Block (CRB) - All unit control blocks 
describing device units attached to a particular controller contain a 
pointer to a single channel request block. The channel request’ block 
contains the following information: : 


e Code that transfers control to a driver interrupt’ service 
routine 


e Addresses of driver's unit and controller initialization 
routines 


e Reference to the device's UNIBUS adapter 


e A pointer to the interrupt data block, which further describes 
the controller 


Controllers can be either multiunit or dedicated. A dedicated 
controller has only one device unit. The VAX/VMS operating system 
does not use the channel request block to synchronize I/O operations 
for a dedicated controller. The channel request block still is 
present and used by drivers and operating system routines. 


For multiunit controllers, a VAX/VMS routine uses a field in the 
Channel request block to arbitrate driver requests for the controller. 
When the system grantS ownership of a multiunit controller data 
channel to a driver fork process, the fork process can initiate an I/O 
operation on a device attached to that controller. 


The unit control blocks for devices attached to a multiunit controller 
all contain pointers to the same channel request block; this allows 
the operating system to manage the controller data channel. Figure 
5-3 illustrates the data structures required to describe three devices 
on a multiunit controller. 





Figure 5-3 I/0 Data Structures for Three Devices on One Controller 


5.1.2.3 Interrupt Data Block (IDB) and Device Data Block (DDB) - The 
channel request block also points to an interrupt data block. The 
interrupt data base contains three critical data structure addresses: 


e The address of the UCB of the device unit, if any, that 
currently owns the controller data channel 


e The address of the control/status register (CSR); it is’ the 
key to access to device registers 


e The address of the adapter control block (ADP) that describes 
the UNIBUS adapter to which the controller is attached 
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Finally, all unit controller blocks describing device units attached 
to a single controller contain a pointer to a single device data block 
(DDB). The device data block contains the following fields’ that 
identify the device and its driver: 


e The generic device/controller name 
e The name of the device's driver as obtained from the driver 
prologue table; see Chapters 7 and 14 for the use of the 


driver name 


e A pointer to a driver dispatch table that lists the addresses 
of routines in the device driver 


Figure 5-4 illustrates a pair of device data blocks describing a group 
of equivalent devices on two separate controllers. 


CRB 
UCB UCB 
DDB 
eo DEVICE 
oo 
DDB 
UCB 
CRB 


Figure 5-4 I/0 Data Base for Two Controllers 


In Figure 5-4, one controller has a single device unit, and the other 
controller has two device units. Each controller has its own device 
data block. Devices on both controllers share the same driver code. 
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5.1.3 Validating the I/O Function 


Using the I/O data structures described above, the Queue I/O Request 
system service locates the address of the driver's function decision 
table by following a chain of pointers beginning in the UCB of the 
target device for the I/O request, as follows: 


UCB —™ DDB —= DDT —» FDT 


The system service then uses data in the function decision table _ to 
analyze the I/0 function. The service confirms that the function 
specified in the I/O request is a valid function for the device. 


5.1.4 Checking Process I/O Request Quotas 


The Queue I/O Request system service calls a routine that determines 
whether the I/O request being readied will cause the process to exceed 
its quota for outstanding direct or buffered I/O requests. If the 
process remains under quota, the checking routine returns a success 
status to the service, allowing it to continue I/O preprocessing. 


In the case where quota is exceeded, the routine examines the system 
service resource wait flag. If the flag is clear, the routine returns 
a quota exceeded status to the Queue I/O Request system service, which 
aborts the I/O request. 


If the flag is set, the process is placed in a wait state until it 
drops below quota, at which time the quota checking routine returns 
success status to the service. Then, depending on the type of 
function, the system service decreases the process quota of remaining 
buffered or direct I/0 operations. 


5.1.5 Validating the I/O Status Block 


If the I/O request specifies a gquadword I/O status block to receive 
final I/O status information, the Queue I/O Request system service 
determines whether the process issuing the request has write access to 
the status block locations specified. If the process has write 
access, the system service fills the quadword with zeros. If the 
process does not have write access, the system service terminates the 
request with an error status. 


5.1.6 Allocating and Setting Up an I/O Request Packet 


If validation of the I/O request succeeds to this point, the Queue I/O 
Request system service allocates a block of nonpaged system memory to 
contain an I/O request packet. 


Before the system service allocates an I/O request packet, it raises 
the hardware IPL of the processor to IPL$ ASTDEL to block any other 
asynchronous activity in the process. The new IPL prevents’ possible 
termination of the process; process termination would result in the 
operating system's losing track of the system memory allocated for the 
I/O request packet. 


The Queue I/O Request system service attempts to allocate an I/O 
request packet from a linked list of preallocated I/O request packets. 
If no preallocated packets exist, the service calls a VAX/VMS- routine 
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that allocates an I/O request packet from nonpaged pool. This 
allocating routine synchronizes with the rest of the system so that it 
can allocate the memory needed. 


The Queue I/O Request system service continues I/O preprocessing by 
writing the following description of the I/O request into the packet: 


e Size in bytes of the I/O request packet 

e A type field identifying the block as an I/O request packet 
e Access mode of the process at the time of the I/O request 

e Process identification of the requesting process 


e If specified in the I/O request, the address of an AST routine 
and its parameter 


e If the device is file-structured, the address of a control 
block that describes the physical location of part of the file 
(window control block) 


e Address of the target device's unit control block 
e I/0 function code; read/write virtual block functions are 
reduced to their logical equivalents before storing a code 


value 


e Number of event flag to set when I/O processing is complete 
for the I/O request 


e Base software priority of the requesting process 


e If specified in the I/O request, the address of an I/O status 
block 


e Process I/O channel number 


e A flag indicating whether the I/O function is buffered or 
direct I/O 


e A flag indicating whether the I/O request iS an input request 


e A flag indicating whether the process has privilege to perform 
logical or physical I/O functions 


e A flag indicating whether the I/O function is a_ physical I/0 
function 


e If specified in the I/O request, the address and size of a 
diagnostic buffer and a flag indicating that the buffer is 
present 


e If an AST routine is specified in the I/O request, a flag 
indicating that the process quota for the use of ASTs has been 
modified 


The Queue I/O Request system service writes the above fields in the 
I/O request packet because these fields contain device-independent 
data. Driver routines or VAX/VMS common FDT routines must fill in the 
device-dependent portions of the I/O request packet. 


Appendix A illustrates the format of an I/O request packet. 
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5.1.7 Function Decision Table Processing 
The driver function decision table drives’ the device-dependent 


preprocessing of an I/O request. Figure 5-5 illustrates the format of 
a function decision table. 


FUNCTION DECISION TABLE 


VALID 1/0 


FUNCTIONS 
BUFFERED I/O 


2 LONGWORDS 


2 LONGWORDS 


3 LONGWORDS 


3 LONGWORDS 


mule, emcee. Gain, Gaui 





Figure 5-5 Driver Function Decision Table 


The I/O function code specified in an I/O request is a 16-bit value 
consisting of two fields: 


e A 6-bit I/O function code (bits 0 through 5) 
e A 10-bit I/O function modifier (bits 6 through 15) 


The 6-bit function code field permits you to define 64 unique I/0 
Function codes for every device type. Chapter 7 describes how you can 
define these function codes. 


Because each driver can define up to 64 unique I/O function codes, the 
first two entries of a function decision table are two longwords each; 
that is, 64 bits each. The first entry is a bit mask of all valid I/0 
function codes for the device. Each bit represents a unique function 
code. The second entry is a bit mask of those valid codes that are 
also buffered I/O functions. The Queue I/O Request system service 
uses these two bit masks to determine whether the I/O function code is 
valid and whether the operation is to be buffered or direct I/O. 


The remaining entries of a function decision table are three longwords 
each. The first two longwords form a bit mask of I/O function codes. 
The third longword is the address of an I/O preprocessing routine to 
be called for the I/O function codes whose corresponding bits are set 
in the first two longwords. 


9-9 
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The Queue I/O Request system service uses the value of the low-order 
six bits of the I/O function code to determine which bit to check in 
each FDT bit mask. That is, if a function code has a value of 22, the 
system service checks the 23rd bit (bit 22) of each bit mask. 


some of the preprocessing routines are present in the operating system 
because they provide device-independent services. Chapter 8 describes 
these routines. Other routines are in the driver because they perform 
device-dependent services. 


The Queue I/O Request system service uses the 3-longword entries’ in 
the function decision table to call I/O preprocessing routines in the 
driver or system, as follows: 


e If the bit in the FDT entry corresponding to the value of the 
function code is set, the system service calls the associated 
preprocessing routine; that is, the routine whose address is 
in the longword following the bit mask. 


e If the bit corresponding to the I/O function code value is not 
set, the Queuve I/O Request system service advances to the next 
FDT entry bit mask and repeats the step above. 


e When the preprocessing routine completes its activity, the 
routine either returns control to the system service or 
transfers control to a VAX/VMS routine that queues the I/0 
request packet or completes the request. 


e If the Queue I/O Request system service regains control, the 
routine advances’ to the next FDT entry and repeats the first 
step above. 


e If all preprocessing for the I/O function is complete, _ the 
preprocessing routine does not return to the Queue I/O Request 
system service. Instead, the routine transfers control _ to 
either a VAX/VMS routine that queues the I/O request for the 
driver's start I/O routine or a VAX/VMS routine to complete or 
abort the request. 


Figure 5-6 illustrates the use of FDT routines in I/O preprocessing. 


As illustrated in Figure 5-6, FDT routines are responsible for ending 
the Queue I/O Request system service's scan of the function decision 
table. For every valid I/O function code for a device, one FDT entry 
must cause I/O preprocessing for the function to end. 


FDT routines execute in the full process context of the process’ that 
requested the I/0 operation. Thus, FDT routines can gain access to 
process virtual address’ space. Once. all FDT preprocessing is 
complete, however, the rest of the processing for the I/O request 
continues in the limited context of a driver fork process or an 
interrupt service routine. 


5-2 HANDLING DEVICE ACTIVITY 


When I/O preprocessing is complete, but the I/O operation iS not yet 
complete, an FDT routine transfers control to a VAX/VMS I/O packet 
queuing routine that arbitrates device activity. The arbitration 
routine ensures that it creates only one driver fork process at a time 
for each device unit on the system. One fork process handles one I/O 
request packet. 
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5.2.1 Creating a Driver Fork Process to Start I/0 


The I/O packet queuing routine determines whether a driver fork 
process exists for the target device, as follows: 


e If the device is idle, no driver fork process exists for the 
device; in this case, the queuing routine immediately creates 
a driver fork process to execute the start I/O routine and 
transfers control to it. 


e If the device is busy, a driver fork process already exists 
for the device; in this case, the queuing routine inserts the 
I/O request packet into a queue of I/O request packets waiting 
for the device unit. The routine queues the packet according 
to the base priority of the caller. Within each priority, 
packets are in first-in/first-out order. 


In the latter case, by the time the driver's start I/O routine gains 
control to dequeue the I/O packet, the originating user's process 
context is no longer available. The driver must execute in the 
reduced context of a driver fork process. Because the context of the 
process initiating the I/O request is not guaranteed to a driver's 
Start I/O routine, the VAX/VMS I/O packet queuing routine always 
initiates the driver's start I/O routine with a context that is 
appropriate for a fork process. The driver fork process consists of 
three registers (or fewer) and a PC. The I/O packet queuing routine 
establishes this context in the following steps: 


e It raises IPL to driver fork IPL. 
e It loads the address of the I/O request packet into R3. 


e It loads the address of the device's unit control block § into 
R5. 


e It transfers control to the driver's start I/O routine entry 
point uSing a JMP instruction. 


The newly activated driver fork process executes under the following 
constraints: 


e It cannot refer to the address space of the process initiating 
the I/O request. 


® It can uSe only RO through R5 freely. It must save other 
registers before uSe and restore them after uSe. 7 


e It must clean up the stack after use. The stack must be in 
its original state when the fork process relinquishes control 
to any VAX/VMS routine. 

e It must execute at IPLS between driver fork level and 
IPL$ POWER. It muSt not lower IPL below device fork except by 
creating a fork process at a lower IPL. 


Each driver fork process executes until one of the following events 
occurs: 


e Device-dependent processing of the I/O request is complete. 


e A shared resource needed by the driver is unavailable, as 
described in Section 3.3. 


e Device activity requires the fork process to wait for a device 
interrupt. 


p= 12 
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5.2.2 Activating a Device and Waiting for an Interrupt 


A device driver's start I/O routine examines the I/O request packet to 
determine the type of I/0 operation to perform and the I/O request 
specification. Depending on the device type supported by the driver, 
the start I/O routine performs some or all of the following steps: 


e Analyzes the I/O function and branches to driver code that 
prepares the unit control block and the device for that I/0 
operation 


e Copies I/O request packet fields into the unit control block 


e Tests fields in the unit control block to determine whether 
the device and/or volume mounted on the device are valid 


e If the device is attached to a multiunit controller, obtains 
the controller data channel 


e If the I/O operation is a DMA transfer, obtains a UNIBUS 
adapter data path and loads UNIBUS adapter map registers 


e Loads all necessary device registers except for the device's 
control/status register 


e Raises IPL to IPLS POWER and confirms that a power failure 
that would invalidate the device operation has not occurred 


e Loads the device's control/status register to activate the 
device 


e Invokes a VAX/VMS routine to suspend the driver fork process 
until a device interrupt or timeout occurs 


While the driver is suspended, the context saved for it consists of 
the unit control block. The context contains the following 
information: 

e A description of the I/O request and the state of the device 


e The contents of R3 and R4 


e Implicit contents of R5 as the address of the unit control 
block 


e A driver return address 

e The address of a device timeout handler 

e Time at which the device will time out 
By convention, R4 often contains the address of the control/status 
register (CSR); it permits the driver to examine device registers. 
When the driver fork process’ regains control after interrupt 


processing, R5 contains the UCB address; it is the key to the rest of 
the I/O data base that is relevant to the current I/O operation. 
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5.2.3 Handling a Device Interrupt 


Once the driver's start I/O routine initiates the transfer, the driver 
invokes a VAX/VMS routine to wait for an interrupt. When the device 
requests an interrupt, the processor dispatches the interrupt to the 
UNIBUS adapter interrupt service routine. This routine determines 
whether a device requested the interrupt or the UNIBUS') adapter 
requested the interrupt because of a UBA error condition. If a UNIBUS 
adapter error caused the interrupt, the system handles the error. 


If a device requested the interrupt, the UNIBUS adapter interrupt 
service routine transfers control to the driver interrupt service 
routine. The driver's interrupt service routine runs at a high 
interrupt priority level so that the routine can service interrupts 
quickly. A driver interrupt service routine usually performs’ the 
following processing. 


e For multiunit device controllers, determines which device unit 
generated the interrupt 


e Examines the unit control block for the device to confirm that 
the driver fork process expects the interrupt 


e Saves device registers 

e Reactivates the suspended driver fork process 
If necessary, the reactivated driver fork process executes at the high 
IPL of the interrupt service routine for a few instructions. Very 


soon, however, the driver lowers its execution priority so that it 
does not block subsequent interrupts for other devices in the system. 


5.2.4 Switching from Interrupt to Fork Process Context 


To lower its priority, the driver calls a VAX/VMS fork process queuing 
routine (IOFORK) that performs the following steps: 


e Disables the timeout that was specified in the wait for 
interrupt routine 


e Saves R3 and R4; these are the registers needed to execute as 
a fork process 


e Saves the address of the instruction following the IOFORK 
request in the UCB fork block 


e Places the address of the UCB fork block from R5 in ae fork 
queue for the driver's fork level 


e Returns to the driver's interrupt service routine 
The interrupt service routine then cleans up the stack, restores 


registers, and dismisses the interrupt. Figure 5-7 illustrates the 
flow of a driver to create a fork process after a device interrupt. 
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Figure 5-7 Creating a Fork Process After an Interrupt 


5.2.5 Activating a Fork Process from a Fork Queue 


When no hardware interrupts are pending, the software interrupt 
priority arbitration logic of the processor transfers control to the 
software interrupt fork dispatcher. One interrupt service routine 
handles all interrupts for fork process dispatching. When the 
processor grants an interrupt at a fork IPL, the fork dispatcher 
processes the fork queue that corresponds to the IPL of the interrupt. 
To do so, the dispatcher performs the following steps: 


@e Removes a driver fork block from the fork queue 
e Restores fork context 
e Transfers control back to the fork process 


Thus, the driver code calls VAX/VMS code that coordinates suspension 
and restoration of a driver fork process. This convention allows 
VAX/VMS to service hardware device interrupts in a timely manner’ and 
reactivate driver fork processes aS soon as no device requires 
attention. 


When a given fork process completes, the fork dispatcher removes’ the 
next entry, if any, from the fork queue, restores its fork process 
context, and reactivates it. This sequence repeats until the _ fork 
queue is empty. When the queue is empty, the fork dispatcher reStores 
RO through R5 from the stack and dismisses the interrupt with an _ REI 
instruction. 


Figure 5-8 illustrates the reactivation of a driver fork process. 
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Figure 5-8 Reactivation of a Driver Fork Process 


5.3 COMPLETION OF AN I/O REQUEST 


Once reactivated, a driver fork process completes the I/O request as 
follows: 


e Releases shared driver resources such as UNIBUS adapter and 
map registers and ownership of the controller 


e Returns status to the VAX/VMS I/O completion routine 


The I/O completion routine performs the following steps to. start 
postprocessing of the I/O request and to start processing the next I/0 
request in the device's queue: 


e Writes return status from the driver into the I/O request 
packet 


e Inserts the finished I/O request packet in the I/O 
postprocessing fork queue and requests an interrupt at 
IPLS$ IOPOST 


e Creates a new fork process for the next I/O request packet in 
the device's I/O request packet wait queue 


e Activates the new driver fork process 
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5.3.1 1/0 Postprocessing 


When processor priority drops below the I/O postprocessing IPL, the 
processor dispatches to the I/0 postprocessing interrupt service 
routine. This VAX/VMS routine completes device-independent processing 
of the I/O request. 


Using the I/O request packet as a source of information, the I/0 
postprocessing dispatcher executes the sequence below for each I/0 
request packet in the postprocessing queue: 


e Removes the I/O request packet from the queue 


e If the I/O function was a direct I/O function, adjusts’ the 
recorded use of the issuing process's direct I/O quota and 
unlocks the pages involved in the I/O transfer 


e If the I/O function was a buffered I/O function, adjusts’ the 
recorded use of the issuing process's buffered I/O quota and, 
if the I/O was a write function, deallocates the system 
buffers used in the transfer 


e Posts the event flag associated with the I/O request 


e Queues a kernel mode AST routine to the image that issued the 
Queue I/O Request system service call 


The queuing of a kernel mode AST routine allows I/O postprocessing to 
execute in the context of the user process but in a privileged access 
mode. Process context is needed to return the results of the I/O 
operation to the process's address space. The kernel mode AST routine 
writes the following data into the process's address space: 


e Data read in a buffered I/O operation 


e If specified in the I/O request, the contents of the 
diagnostic buffer 


e If specified in the I/O request, the two longwords of I/0 
Status 


If the I/O request specifies a user AST routine, the kernel mode AST 
routine queues the uSer mode AST for the process. When VAX/VMS 
delivers the user mode AST, the system AST delivery routine 
deallocates the I/O request packet. The first part of an I/O request 
packet is the AST control block for user requested ASTs. 


PART Il 


Device drivers consist of static tables, routines that perform I/0 
preprocessing, and routines that handle the device and controller. 
The chapters that follow describe how to code the following sections 
of a driver: 

e Static tables 

e Function decision table routines 


e Routines that start an I/O operation on the device and 
complete the I/0 operation 


e Interrupt service routines 


e Routines that request allocation of UNIBUS adapter- map 
registers and data paths 


e Routines that initialize devices and controllers 
e Routines that cancel an I/O operation 
e Error-logging routines 
The “how to" chapters listed above are preceded by a chapter that 
contains a driver template. The template illustrates the general 
organization and coding of a driver. 
NOTE 
The "how to" chapters describe a common 
approach to the coding of various driver 
routines; they are examples. They do 


not present the only approach that can 
be taken to coding a driver. 


CHAPTER 6 


TEMPLATE FOR AN I/O. DRIVER 


The pages that follow describe conventions to be used by device 
drivers and provide a template for a device driver. Drivers do not 
necessarily need all of the routines indicated by the template, nor do 
driver routines and tables need to follow the exact order of the 
template. However, the VAX/VMS operating system does place ae few 
restrictions on the order and content of driver routines and tables. 


Figure 6-1 illustrates the organization of a device driver. The first 
item in a device driver is the driver prologue table. This table must 
be the first generated code ina driver. The order of the remaining 
tables and routines varies from driver to driver. However, the last 
Statement in every driver, except for the .END assembly directive, 
must be a label marking the end of the driver. The address of this 
label is stored in the driver prologue table. The driver loading 
procedure uses this address to calculate the size of the driver. This 
address allows the driver loading procedure to compute the size of the 
driver. Chapter 14 describes the driver loading procedure. 


Some drivers contain no device-dependent function decision table 
routines. Other drivers need only minimal initialization procedures. 
However, every driver normally contains static driver tables and a 
Start I/O routine or an interrupt service routine. 


6.1 CODING CONVENTIONS 


The driver loading procedure loads a device driver into a block of 
nonpaged system memory whose location is chosen by the operating 
system memory allocation routines. Therefore, the driver must consist 
of position-independent code only. 


In addition, the system may call a device driver repeatedly to process 
I/O requests and interrupts. The driver often does not complete one 
I/O operation before the system transfers control to the driver to 
begin another on a different unit. For this reason, the code must be 
reentrant. 
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Figure 6-1 Driver Organization 


The rules of position-independent and reentrant code are listed below. 


Code can branch only to relative addresses within the driver 
and to global addresses listed in the VAX/VMS symbol table 
(SYS.STB in SYSSSYSTEM:). 


Static tables can list only relative addresses within the 
driver and global addresses. 


The driver cannot store temporary data in local driver tables 
for dynamic driver context. All dynamic temporary storage 
must be contained within the unit control block corresponding 
to an I/O request or the current I/O request block. 


The driver refers to the I/O data base by loading the address 
of a data structure into a general register and uSing 
displacement addressing to the fields of the data structure. 


Refer to the VAX-11 MACRO User's Guide for additional information 








about position-independent and reentrant code. 
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Device drivers must also restrict their use of general registers and 
the stack: 


FDT routines can use RO through R2 and R9 through Rll as 
scratch registers. The routines can uSe other registers by 
saving the registers before use and restoring them before 
exiting from the FDT routine. 


All other driver routines can use RO through R5 as_~— scratch 
registers. The routines can use other registers, if 
necessary, by saving and restoring them but are discouraged 
from so doing. 


All driver routines can use the stack for temporary storage 
only if the routines restore the stack to itS previous state 
before calling any VAX/VMS-~ routines or executing RSB 
instructions. 


6.2 RESTRICTIONS ON DEVICE REGISTER I/O SPACE USE 


The programmer of a device driver for a UNIBUS device must observe the 
following restrictions on the use of a device registers: 


Drivers should always store the address of a device control 
register in a general register and then gain access to the 
driver indirectly through the general register. The example 
below defines symbolic word offsets for each device register 
and gains access to them using displacement mode addressing 
From R4. 


Device register offsets 


=e se Oe 


LP_CSR 
LP DBR 


CSR offset 
Buffer address offset 


| 
© 
=e “8 


Get address of CRB 
Get the address of 
the device's CSR 


MOVL UCBSL_CRB(R5) ,R4 
MOVL  CRBSL_INTD+VECSL_IDB(R4) ,R4 


=e 66 6% 


TSTW LP _CSR(R4) ; Is printer online? 


Floating, double, field, queue, or quadword operands are not 
allowed in I/0 address space, nor can an instruction obtain 
the position, size, length, or base of an operand from I/O 
Space. For example, a driver cannot uSe a field instruction 
to test a bit in a device register. 


Drivers cannot use string instructions because they are 
restartahble. 


Drivers can use only those instructions with a maximum of one 
modify or write destination. The destination must be the last 
operand. 
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Registers of devices connected to the SBI (for example, UNIBUS 
adapter device registers and MASSBUS device registers) are 
longwords. Registers of devices connected to the UNIBUS are 
words. Instructions that refer to UNIBUS adapter registers 
must use longword context. All driver instructions’ that 
affect UNIBUS device registers must use word context, for 
example, BISW, MOVW, and ADDW3, unless the register is 
byte-addressable. 


Some UNIBUS devices, such as the LPll, use byte-addressable 
registers. When a device driver refers to this type of 
register, it can use byte-context instructions (MOVB, BISB, 
and so on). 


Unaligned references and references uSing a length attribute 
other than the length of the register may produce 
unpredictable results. For example, if an instruction makes a 
byte reference to a word-addressable register, the byte 
addressed may not be modified or supplied. If an instruction 
makes a word reference to a #UNIBUS adapter register, the 
system Signals a machine check exception. 


After an instruction refers to I/O space, it must not handle 
an exception or interrupt. If the instruction is allowed to 
restart, it will re-read the device register, which causes 
undesirable device side-effects or data loss. This rule 
applies to device driver instructions and instructions within 
processes that have called the Create and Map Section system 
service to map part of UNIBUS I/O space. 


Also, if an instruction executes above IPLS ASTDEL, it must 
not incur an exception or a page fault; if it does, the 
operating system signals a bugcheck. 


To access I/O space, use the instructions listed below. These 
instructions are not interruptible unless they use 
autoincrement deferred addressing mode or any of the 
displacement deferred modes when specifying an operand. 


ADAWI MCOM (B,W,L) 
ADD (B,W,L) 2 MFPR 
ADD(B,W,L) 3 MNEG (B,W,L) 
ADWC MOV (B,W,L) 
BIC (B,W,L) 2 MOVA(B,W,L) 
BIC (B,W,L) 3 MOV AQ 
BICPSW MOVPSL 
BIS(B,W,L) 2 MOVZ (BW,BL ,WL) 
BIS(B,W,L) 3 MTPR 
BISPSL PROBE (R,W) 
BISPSW PUSHA (B,W,L) 
BIT(B,W,L) PUSHAQ 
CASE(B,W,L) PUSHL 
CHM (K,E,S,U) SBWC 
CLR(B,W,L) SUB (B,W,L) 2 
CMP (B,W,L) SUB (B,W,L) 3 
CVT (BW,BL ,WB, TST (B,W,L) 
WL,LB, LW) XOR(B,W,L) 2 
DEC (B,W,L) XOR(B,W,L) 3 


INC (B,W,L) 
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-TITLE TDRIVER - VAX/VMS TEMPLATE DRIVER 
~IDENT ‘'V02-000' 


SSIS ICIS GIGI GIGI GGG GIGI GIGI GOI ICI GIGI GIGI GCG ICICI GIGI IOI ISIS TOI ITO OICK 
ox * 
f 

;* Copyright (c) 1978,1979,1980 - 
;* by DIGITAL Equipment Corporation, Maynard, Mass. * 
°* * 
f 

;* This software is furnished under a license and may be used and copied * 
;* only in accordance with the terms of such license and with the * 
;* inclusion of the above copyright notice. This software or any other * 
;* copies thereof may not be provided or otherwise made available to any * 
;* other person. No title to and ownership of the software is hereby * 
;* transferred. = 
;* * 
;* The information in this software is Subject to change without notice * 
;* and should not be construed aS a commitment by DIGITAL Equipment * 
7;* Corporation. ° 
i * 
;* DIGITAL assumes no reSponsibility for the use or reliability of its * 
;* software on equipment which is not supplied by DIGITAL. * 
ok * 
RIGGS CIOI SII GIIIGIGI ICICI GIGI ITO ISI TCI GIGI III GCI III ITOI II TOI III 
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S. Programmer L1-NOV-1979 
REVISION HISTORY: 


V02 JHPOO1l J. Programmer 2-Aug-1979 La e2y 
Remove BLBC instruction from CANCEL routine. 
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; FACILITY: 

; 

: VAX/VMS Template driver 

; 

; ABSTRACT: 

; 

; This module contains the outline of a driver: 
; 

: Models of driver tables 

: Controller and unit initialization routines 
: An FDT routine 

: The start I/O routine 

: The interrupt service routine 

: The cancel I/O routine 

: The device register dump routine 
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External and local symbol 


External symbols 


constants 


TD DEF _BUFSIZ 
TD TIMEOUT SEC 
TD NUM REGS 


=e to SE 


SDEF 
SDEF 
SDEF 
SDEF 
SDEF 


SDEF 


™=s “Ne GS 


1024 
10 


SDEFINI UCB 


.=UCBSK_LENGTH 


UCBSW_TD_WORD 


» BLKW 


UCBSW TD STATUS 


-BLKW 


UCBSW_TD_WRDCNT 


-BLKW 


UCBSW_TD_BUFADR 


UCBSW_TD_DATBUF 


»- BLKW 


~-BLKW 


UCBSK_TD UCBLEN 


me ee *e Ve Ne We Wo We We Be We 


=e te Se =O 6% 6 


=e 6™e 6%~e 


=e =e 


=e 


=8 


DRIVER 


definitions 


Channel request block 
Device classes and types 
Device data block 

Device characteristics 
Interrupt data block 

I/O function codes 
Hardware IPL definitions 
I/O request packet 
System status codes 

Unit control block 
Interrupt vector block 


Argument list (AP) offsets for device-dependent QIO parameters 


First QIO parameter 
Second QIO parameter 
Third QIO parameter 
Fourth QIO parameter 
Fifth QIO parameter 
Sixth QIO parameter 


Default buffer size 
10 second device timeout 
Device has 4 registers 


Definitions that follow the standard UCB fields 


Start of UCB definitions 
Position at end of UCB 

A sample word 

Device's CSR register 
Device's word count register 
Device's buffer address 
register 


Device's data buffer register 


Length of extended UCB 


Bit positions for device-dependent status field in UCB 


=e eo te 


SDEF 


me %e 6 


SDEF 
SDEF 


SDEF 
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SVIELD UCB,0,<- 
<BIT_ ZERO, ,M>,- 
<BIT ONE, »M> rr 
> 


SDEFEND UCB 


SDEFINI TD 


TD STATUS 
._BLKW 1 


VIELD TD STS,0,<- 
~~ <GO,,M>,- 

<BIT1,,M>,- 
<BIT2,,M>,- 
<BIT3,,M>,- 
<XBA,2,M>,- 
<INTEN,,M>,- 
<READY,,M>,- 
<BIT8,,M>,- 
<BIT9,,M>,- 
<BIT10,,M>,- 
<BIT11,,M>,- 


<,1>,- 
<ATTN, ,M>,- 
<NEX,,M>,- 
<ERROR,,M>,- 
> 
TD _WRDCNT 
.BLKW 1 
TD BUFADR 
.BLKW 1 
TD DATBUF 
3 .BLKW 1 
SDEFEND TD 


1/0 


=e se BE 


=e 


Device register offsets from CSR address 


=e 


Bit positions for device control/status 
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Device status 
First bit 
Second bit 


End of UCB definitions 


Start of status definitions 


Control/status 


register 


Control/status register 
Start device 

Bit one 

Bit two 

Bit three 

Extended address bits 
Enable interrupts 

Device ready for command 
Bit eight 

Bit nine 

Bit ten 

Bit eleven 

Disregarded bit 
Attention bit 
Nonexistent memory flag 
Error or external interrupt 


Word count 
Buffer address 
Data buffer 


End of device register 
definitions. 
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-SBTTL Standard tables 


Driver prologue table 


=e Se) 6% 


DPTAB - ; DPT-creation macro 
END=TD_END,- End of driver label 
ADAPTER=UBA,- Adapter type 
UCBSIZE=<UCBSK TD UCBLEN>,-~ Length of UCB 
NAME=TDDRIVER Driver name 

DPT STORE INIT Start of load 

7 initialization table 

Device fork IPL 

Device interrupt IPL 

Device characteristics 

input device 
output device 

Sample device class 

Default buffer size 


DPT STORE UCB,UCBSB FIPL,B,8 
DPT STORE UCB,UCBSB DIPL,B,22 
DPT STORE UCB, UCBSL__ DEVCHAR, L,<- 
DEVSM IDV!-_ 
DEVSM ODV> 
DPT STORE UCB,UCBSB DEVCLASS,B, DC$_SCOM 
DPT STORE UCB,UCBSW DEVBUFSIZ ae 
7 TD DEF BUFSIZ 


me “ese “ee “SO Ne “Se TO Me Me BSE OMS OMS UME CUT 


DPT STORE REINIT - Start of reload 

7 initialization table 
Address of DDT 

Address of interrupt 
service routine 
Address of controller 
initialization routine 


DPT STORE DDB,DDBSL DDT,D,TDSDDT 
DPT STORE CRB,CRBSL INTD+4, D,- 
TD INTERRUPT 
DPT STORE CRB,- 
CRBSL INTD+VECSL INITIAL,- 
D,TD CONTROL _ INIT 
DPT STORE CRB,- 
CRBSL INTD+VECSL _UNITINIT,-~ 
D,TD_ UNIT_ INIT 
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Address of device 
unit initialization 
routine 


=e "se We 


End of initialization 
tables 


DPT STORE END 


me 6" Oe 


Driver dispatch table 
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DDTAB ~ * DDT-creation macro 
DEVNAM=TD ,-~ Name of device 
START=TD START,- Start I/O routine 
FUNCTB=TD FUNCTABLE,- FDT address 
CANCEL=TD CANCEL,- Cancel I/O routine 
REGDMP=TD REG DUMP Register dump routine 
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: 
: Function decision table 


e 
‘ 


TD _FUNCTABLE: - FDT for driver 
FUNCTAB ,- Valid I/O functions 


<READVBLK ,- : Read virtual 

READLBLK ,- ; Read logical 

READPBLK ,- ; Read physical 

WRITEVBLK ,- ; Write virtual 

WRITELBLK,- ; Write logical 

WRITEPBLK ,- ; Write physical 

SETMODE,- ; Set device mode 

SETCHAR> : Set device chars. 
FUNCTAB , * No buffered functions 


FUNCTAB +EXESREAD,- FDT read routine for 


FUNCTAB 


FUNCTAB 


TEMPLATE FOR AN I/O DRIVER 


<READVBLK ,- 
READLBLK,- 
READPBLK> 
+EXESWRITE,- 
<WRITEVBLK ,- 
WRITELBLK ,- 
WRITEPBLK> 
+EXESSETMODE,- 
<SETCHAR,- 
SETMODE> 
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read virtual, 

read logical, 

and read physical. 
FDT write routine for 
write virtual, 

write logical, 

and write physical. 


FDT set mode routine 


for set chars. and 
set mode. 


TEMPLATE FOR AN I/O DRIVER 


-SBTTL TD CONTROL INIT, Controller initialization routine 


+ 
+ 


Functional description: 


Inputs: 
R4 - address 
R5 - address 
R6 ~- address 
R8 - address 
Outputs: 
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TD CONTROL INIT: 
RSB 


of 
of 
of 
of 


at system startup 
during driver loading and reloading 
during recovery from a power failure 


the 
the 
the 
the 


CSR 
IDB 
DDB 
CRB 


TD CONTROL INIT, Readies controller for I/O operations 


The operating system calls this routine in 3 places: 


(controller status register) 
(interrupt data block) 
(device data block) 

(channel request block) 


The routine must preserve all registers except RO-R3. 


* Initialize controller 
; Return 


TEMPLATE FOR AN I/O DRIVER 


~-SBTTL TD UNIT INIT, Unit initialization routine 


+ 
+ 


TD_UNIT INIT, Readies unit for I/O operations 
Functional description: 


The operating system calls this routine after calling the 
controller initialization routine: 


at system startup 
during driver loading 
during recovery from a power failure 


Inputs: 
R4 - address of the CSR (controller status register) 
R5 - address of the UCB (unit control block) 
Outputs: 


The routine must preserve all registers except RO-R3. 
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TD_UNIT INIT: : Initialize unit 
BISW #UCBSM ONLINE, - 
UCBSW STS(R5) > Set unit online 
RSB i ; Return 


TEMPLATE FOR AN I/O DRIVER 


-SBTTL TD FDT ROUTINE, Sample FDT routine 


t+ 


TD FDOT ROUTINE, Sample FDT routine 


Functional description: 


SUPPLIED BY USER 


Inputs: 

RO-R2 - scratch registers 

R3 - address of the IRP (I/O request packet) 

R4 - address of the PCB (process control block) 

address of the UCB (unit control block) 

R6 - address of the CCB (channel control block) 

R7 - bit number of the I/O function code 

R8 - address of the FDT table entry for this routine 

R9-R1l - scratch registers 

AP - address of the lst function dependent QIO parameter 
Outputs: 


The routine must preserve all registers except RO-R2, and 


R9-R11. 
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TD FDT ROUTINE: 
RSB 


; Sample FDT routine 
; Return 


TEMPLATE FOR 


AN I/O DRIVER 


-SBTTL TD START, Start I/0 routine 


+ 
+ 


Functional description: 


SUPPLIED BY USER 


The routine must preserve 
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Lr 


TD START: 


TD START - Start a transmit, receive, or set mode operation 


Inputs: 
R3 - address of the IRP (I/O request packet) 
R5 - address of the UCB (unit control block) 
Outputs: 
RO - lst longword of I/O status: contains status code and 
number of bytes transferred 
Rl - 2nd longword of I/O status: device-dependent 


all registers except RO-R2 and R4. 


; Process an I/O packet 


WFIKPCH TD _TIMEOUT,#TD TIMEOUT SEC 


me SNe Me NO 


IOFORK 

INSV UCBSW BCNT(R5) , #16 
#16,RO 

MOVW #SS$ NORMAL ,RO 


Call I/O postprocessing. 


me 6 Se 


COMPLETE I0: 
REQCOM 


Device timeout handling. Return 
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TD TIMEOUT: 
7 SETIPL UCBSB FIPL(R5) 
MOVZWL #SSS TIMEOUT,RO 
BRB COMPLETE IO 


After a transfer completes successfully, return the number of bytes 
transferred and a success status code, 


Load number of bytes trans- 
ferred into high word of RO. 
Load a success code into RO. 


Prod 


ue *Oe We 


Driver processing is finished. 
Complete I/0. 
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an error status code, 


Timeout handling 

Lower to driver fork IPL 
Return error status. 
Call I/O postprocessing. 
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+ 
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TEMPLATE FOR AN I/O DRIVER 


-SBTTL TD INTERRUPT, Interrupt service routine 


The sample code assumes either 


Inputs: 


0 (SP) 


4(SP) 
8 (SP) 
12 (SP) 
16 (SP) 
20 (SP) 
24 (SP) 
28 (SP) 
32 (SP) 


The IDB 


Outputs: 


Functional description: 


TD INTERRUPT, Analyzes interrupts, processes solicited interrupts 


that the driver is for a single-unit controller, and 
that the unit initialization code has stored the 
address of the UCB in the IDB; or 


that the driver's start I/O routine acquired the 
controller's channel with a REQPCHANL macro call, and 
then invoked the WFIKPCH macro to keep the channel 
while waiting for an interrupt. 


- pointer to the address of the IDB (interrupt data 


block ) 
- saved RO 
- saved Rl 
- saved R2 
~ saved R3 
~ saved R4 
~ saved R5 


- saved PSL (program status longword) 


- saved PC 


contains the CSR address and the UCB address. 


The routine must preserve all registers except RO-R5. 


TD INTERRUPT: 
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=e 


MOVL 


MOVL 


MOVL 
BBCC 


MOVW 


MOVW 


MOVW 


MOVW 


@(SP)+,R4 
IDB$L_OWNER(R4) ,R5 


IDBSL CSR(R4) ,R4 
#UCBSV INT,- 

UCBSW STS(R5),- 
UNSOL INTERRUPT 


This is a solicited interrupt. Save 
the contents of the device registers in 


TD STATUS (R4) ,- 
UCBSW TD STATUS (R5) 
TD WRDCNT(R4) ,- 
UCBSW TD WRDCNT(R5) 
TD BUFADR(R4) ,- 
UCBSW TD BUFADR(RS5) 
TD DATBUF(R4) ,- 
UCBSW_TD_DATBUF(R5) 


me “eo “se Be Bp WO We WO 
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Service device interrupt 

Get address of IDB and remove 
pointer from stack. 

Get address of device owner's 
UCB. 

Get address of device's CSR. 
If device doesS not expect 
interrupt, dismiss it. 


the UCB. 


Otherwise, save all device 
registers. First the CSR. 
Save the word count register. 


Save the buffer address 
register. 
Save the data buffer register. 


TEMPLATE FOR AN I/0 


Restore control to the main driver. 


e 
’ 
° 
e 


RESTORE DRIVER: 
MOVL UCBSL_FR3(R5) ,R3 


JSB @UCBSL_ FPC(R5) 


Dismiss the interrupt. 
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UNSOL_INTERRUPT: 
POPR #°“M<RO,R1,R2,R3,R4,R5> 
REL 
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DRIVER 


Jump to main driver code. 
Restore driver's R3 (use a 
MOVQ to restore R3-R4). 
Call driver at interrupt 
wait address. 


Dismiss unsolicited interrupt. 
Restore RO-R5 
Return from interrupt. 


TEMPLATE FOR AN I/O DRIVER 


-SBTTL TD CANCEL, Cancel I/O routine 


Sa 
+ 


TD_CANCEL, Cancels an I/O operation in progress 
Functional description: 


This routine calls IOCSCANCELIO to set the cancel bit in the 
UCB status word if: 


the device is busy, 
the IRP's process ID matches the cancel process ID, 
the IRP channel matches the cancel channel. 


If IOCSCANCELIO sets the cancel bit, then this driver routine 
does device-dependent cancel I/O fixups. 


Inputs: 
R2 - negated value of the channel index number 
R3 - address of the current IRP (I/O request packet) 
R4 - address of the PCB (process control] block) for the 
process canceling I/O 
R5 ~ address of the UCB (unit control block) 
Outputs: 


The routine must preserve all registers except RO-R3. 


The routine may set the UCBSM CANCEL bit in UCBSW_STS. 
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Cancel an I/O operation 

Set cancel bit if appropriate. 
If the cancel bit is not set, 
just return. 


TD CANCEL: | 

= JSB G*IOCSCANCELIO 

BBC #UCBSV CANCEL,- 
UCBSW_STS(R5) ,10$ 
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; Device-dependent cancel operations go next. 


Finally, the return. 


=e ss “Be 


10S: 
RSB > Return 


TEMPLATE FOR AN I/O DRIVER 


~-SBTTL TD REG DUMP, Device register dump routine 


+ 
+ 


TD_REG DUMP, Dumps the contents of device registers to a buffer 
Functional description: 


Writes the number of device registers, and their current 
contents into a diagnostic or error buffer. 


Inputs: 
RO - address of the output buffer 
R4 - address of the CSR (controller status register) 
R5 - address of the UCB (unit control block) 
Outputs: 


The routine must preserve all registers except R1-R3. 


The output buffer contains the current contents of the device 
registers. RO contains the address of the next empty longword in 
the output buffer. 7 
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TD REG DUMP: 
MOVZBL #TD_NUM REGS, (RO) + 
MOVZWL UCBSW_TD STATUS(R5) ,- 


Dump device registers 
Store device register count. 
Store device status register. 
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(RO) + 

MOVZWL UCBSW TD WRDCNT(R5),- ; Store word count register. 
(RO)+ — 

MOVZWL UCBSW_ TD BUFADR(R5) ,- ; Store buffer address register. 
(RO) + 

MOVZWL UCBSW_TD_DATBUF(R5) ,- > Store data huffer register. 
(RO) + 

RSB ; Return 


TEMPLATE FOR AN I/O DRIVER 


-SBTTL TD END, End of driver 


i 
; Label that marks the end of the driver 


? 


TD_END: : Last location in driver 
- END 


CHAPTER 7 


CODING DEVICE DRIVER TABLES 


Every device driver declares three static tables that describe the 
device and driver: 


e Driver prologue table that describes the device type, driver 
name, and fields in the I/O data base to be initialized during 
driver loading and reloading 


e Driver dispatch table that lists some of the driver entry 
points to which VAX/VMS transfers’ control; the channel 
request block and function decision table list other entry 
points 


e Function decision table that lists valid functions of the 
driver and entry points to routines that perform I/0 
preprocessing for each function 


The VAX/VMS operating system provides macros that drivers can invoke 
to create the tables listed above. Descriptions of individual tables 
in the sections that follow also contain descriptions of the macros 
invoked to create the tables. All of the macros described in this 
Chapter are keyword macros; that is, parameter values can be 
expressed in the following format: 


PARAMETER=value 


The VAX-11 MACRO Language Reference Manual describes the syntax rules 
for keyword macros in detail. The sections that follow provide 
examples of macro uSage. 


7.1 DRIVER PROLOGUE TABLE (DPT) 


The driver prologue table is the first generated code in every device 
driver. This table, along with parameters to the SYSGEN command that 
requests driver loading, describes the driver to the driver loading 
procedure. This procedure computes the size of the driver and loads 
it into nonpaged system memory. The procedure also creates’ control 
blocks in the I/O data base for new devices and writes values from the 
driver prologue table into fields of these control blocks, as 
described in Chapter 14. 


To create a driver prologue table, the driver invokes the DPTAB macro, 
described in Section 7.1.1. 


When the DPTAB macro expands, it createS a control block that’ the 


driver loading procedure uses to load the driver. The loading 
procedure loads the driver prologue table and the driver together in 
virtual memory. The loading procedure also links the new driver 
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prologue table into a list of all driver prologue tables known to_ the 
system. | 


Most device drivers need to have certain other fields of the I/O data 
base initialized when the driver and its hardware control blocks are 
loaded. The driver lists these fields in DPT STORE macro invocations 
immediately after the DPTAB macro invocation. The DPT STORE macro 
accepts two lists of fields: — 


e Fields to be initialized when the control blocks are built 
uSing the CONNECT command to SYSGEN 


e Fields to be initialized when the driver is reloaded using the 
RELOAD command to SYSGEN 


The DPTAB macro stores the relative addresses of the two lists in the 
driver prologue table. Section 7.1.2 describes the format of the 
DPT STORE macro. 


Drivers must use the DPT STORE macro to supply initialization data for 
the following fields: 


UCBSB_FIPL Driver fork IPL 
UCBSB_DIPL Hardware device IPL 
UCBSL_DEVCHAR Device characteristics (see 


Appendix A) 


The driver also must provide reinitialization data for the device data 
block field DDBSL DDT and for any of the following routine addresses 
in the channel request block: 


DDBSL DDT Address of the driver dispatch 
table 

CRBSL_INTD+4 Entry point to the driver interrupt 
service routine, if one exists 

CRBSL_INTD+VECSL_ INITIAL Address of a controller 
initialization routine, if one 
exists 

CRBSL_INTD+VECSL UNITINIT Address of a device unit 
initialization routine, if one 


exists. This entry point is used 
by UNIBUS devices. 


7.1.1 #DPTAB Macro 
The DPTAB macro creates a driver prologue table. 
Format 
DPTAB end,adapter, [flags] ,ucbsize, [unload], [maxunits] ,name 


end 
The address of the end of the driver module. 


adapt 


flags 


ucbsi 


unloa 


maxun 


name 


edierd 


The D 
descr 
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er 
The adapter type. 


UBA 
MBA 


UNIBUS adapter 
MASSBUS adapter 


The driver loader flags. 


DPTSM SVP Indicates, when set, that the device requires a 
= permanently allocated system page. This flag 
causes the driver loading procedure to allocate 
a permanent system page table entry for the 
device. The virtual address of the system page 
table entry is written into the system page 
field of the UCB (UCBSL SVPN) during creation 
of the UCB. Disk drivers use this page table 
entry during ECC error correction. 


DPTSM_NOUNLOAD Indicates, when set, that the driver cannot be 
reloaded. A system bootstrap must occur before 
the driver can be reloaded. 


ze 

The size of each device unit control block in bytes. This 
argument is required. This field, when used, allows drivers to 
extend the unit control block to store device-dependent data 
describing an I/O operation. Appendix A’ provides examples. 
Driver routines and VAX/VMS ECC routines interpret fields in the 
extended part of the unit control block. The amount that the 
unit control block is extended is variable for each driver type. 


d 
The address of a routine to call before the driver is reloaded. 
The driver loading procedure calls this routine before 


reinitializing all controllers and device units associated with 
the driver. 


its 

The maximum number of units on a controller that this driver 
supports. This field affects the size of the interrupt data 
block created by SYSGEN's CONNECT command. If this field is 
omitted, the default is 8 units. You can override the maxunits 
field by appending the /MAXUNITS qualifier to the CONNECT command 
to SYSGEN. 


The name of the device driver module. By convention, a driver 
name is formed by appending the string DRIVER to the 2- 
alphabetic character generic device name, for example, DBDRIVER. 


DPT STORE Macro 


PT STORE macro either declares an assembly language label or 
ibes a field to be initialized. When the macro declares a label, 


the macro has format 1. When the DPT STORE macro describes a field to 


be in 


Forma 


itialized, the macro has format 2. 
t l 


DPT STORE label-name 
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label-name 
The name of the label to be declared. It can be one of the 
following: 

INIT Indicates the start of fields to initialize 
when the driver is loaded. 

REINIT Indicates the start of additional fields’ to 
initialize when the driver is loaded or 
reloaded. 

END Indicates the end of the two lists. 

Format 2 
DPT STORE struc_type,struc offset,operation,expression, 
[position], [size] 
struc type 


The type of I/O data base control block that contains the field 
to be initialized. The type can be one of the following: 


DDB device data block 

UCB unit control block 

CRB channel request block 
IDB interrupt dispatch block 


Struc offset 
The unsigned offset into the control block. The driver loading 
procedure can initialize only the first 256 bytes of each data 
structure. Unit and controller initialization routines’ can 
initialize additional data fields. 


operation 
The type of operation to be performed. The type can be one of 
the following: 


write a byte value 

write a word value 

write a longword value 

write an address relative to the driver 
write a bit field 


<OrzW 


The V operation takes the following longword of data and _ the 
position and size arguments as operands of an INSV instruction. 


An at sign (@) preceding the operation parameter indicates’ that 
the expression parameter that follows is’ the address of the 
initialization data. 


expression 
An expresSion to be stored in the control block or, if an at sign 
(@) is specified preceding the operation parameter, the address 
of an expression. For example, the following macro indicates 
that DEVICE CHARS is’ the address of the data to write into the 
DEVCHAR field of the UCB. 


DPT STORE UCB,UCBSL_DEVCHAR,@L,DEVICE CHARS 
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position 
The starting bit position within the specified field. This 
parameter is specified only for V operations. 


size 
The number of bits in the field. This parameter is specified 
only for V operations. 


7.1.3 Example of DPTAB and DPT STORE Macro Use 


The following example invokes the DPTAB macro and DPT STORE macros’ to 
describe a device driver and its data base. 


DPTAB - > Define DPT 
END=XX END,- End of driver 
ADAPTER=UBA,- Adapter type 
UCBSIZE=140,- Size of UCB 
NAME=XXDRIVER Name of driver module 
DPT STORE INIT Start of control block 
initialization values 
Driver fork IPL 
Device characteristics: 
record-oriented 
available 
output device 
Device class 


DPT STORE UCB,UCBSB FIPL,B,8 

DPT STORE UCB,UCBS$L_DEVCHAR,L,- 
<DEVSM REC- 
!DEVSM AVL- 
!DEVSM ODV> 

DPT STORE UCB,UCB$B_DEVCLASS,B,- 
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DC$_XX 

DPT STORE UCB,UCBS$B DEVTYPE,B,- ; Device type 
XX$_XL78 | 

DPT STORE UCB,UCBSW_DEVBUFSIZ,W,- ; Default buffer size 
132. 

DPT STORE UCB,UCB$B_DIPL,B,22 ; Device IPL 


DPT STORE REINIT ; Start of control block 
- + reinitialization values 
DPT STORE CRB,CRBSL INTD+4,D,- ; Interrupt service 

Zz XX INTERRUPT ; routine address 
DPT STORE CRB, CRBSL INTD+VECSL UNITINIT,- 

— D,XX XL78 INIT = > Unit initialization 
i na routine address 
Address of driver 
dispatch table 
End of field 
initialization 


DPT STORE DDB,DDB$L_DDT,D,XX$DDT 


DPT_ STORE END 
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7.2 DRIVER DISPATCH TABLE (DDT) 


The driver dispatch table lists some of the entry points for driver 
routines to be called by VAX/VMS for I/O processing. Every driver 
must create a driver dispatch table. The routines listed can reside 
in the driver module or in a VAX/VMS module. Appendix A describes the 
VAX/VMS device-independent routines that can be specified. 
Device-dependent routines are normally located in the driver module. 
The driver dispatch table contains relative addresses for routines 
located in the driver module and absolute addresses for routines 
located in the operating system. 
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The driver creates the driver dispatch table by invoking the macro 
DDTAB. The driver loading procedure writes the address of the driver 
dispatch table, as specified in a DPT STORE macro, into the device 
data block. ~ 


7.2.1  #DDTAB Macro 


The DDTAB macro creates a driver dispatch table. The table has a 
label of devnamS$DDT. Just preceding the table, DDTAB generates a 
program section with the following statement: 


~PSECT $$$115 DRIVER 
Format 


DDTAB devnam,start, [unsolic],functb, [cancel], [{regdmp], [diagbf], 
ferlgbf], f[unitinit], [altstart] 


devnam 
The generic name of the device driven by this device driver. 


Start 
The address of the driver's start I/O routine. 


unsolic 
The address of the routine that services unsolicited interrupts 
from the device. This field is used by MASSBUS devices. 


functb 
The address of the function decision table for this driver. 


cancel 
The address of the cancel I/O operation routine. 


regdmp 
The address of the routine that dumps the device registers to an 
error log buffer or to a diagnostic buffer. 


diagbf 
The length in bytes of the diagnostic buffer used for this 
device. 


erlgbf | | 
The length in bytes of the error log buffer used for this device. 


unitinit 
The address of the device initialization routine, if one exists. 
MASSBUS' drivers should use this field rather than CRBSL INTD + 
VECS$L_UNITINIT. UNIBUS drivers may use either one. ~ 


altstart 
The alternate start I/O routine. To initiate this routine, use 
the VAX/VMS routine EXESALTOQUEPKT instead of EXESQIODRVPKT. 


The DDTAB macro writes the address of the VAX/VMS routine IOCSRETURN 
into routine address fields of the driver dispatch table that are not 
Supplied in the macro invocation. IOCSRETURN executes an RSB 
instruction; for further information, refer to Appendix C. 
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7.2.2 Example of a DDTAB Macro 
A sample invocation of the DDTAB macro follows. 


DDTAB DEVNAM=XX ,~ 
START=STARTIO,- 
FUNCTB=FUNCTABLE,- 
CANCEL=+IOCSCANCELIO 


Driver dispatch table 
Start I/O operation 
Function decision table 
Cancel I/O 


=e “se te WO 


Notice that a plus sign (+) precedes the address of the entry point to 
the cancel I/O routine. The plus sign indicates that the routine is 
part of VAX/VMS. No plus sign precedes the address of the start I/0 
routine because it is part of the driver module. Omitting a required 
plus sign is a common bug in device drivers. 


7.3 FUNCTION DECISION TABLE (FDT) 


The function decision table lists codes for I/O functions that are 
valid for the device; indicates whether the functions are buffered 
I/O functions; and specifies routines to perform preprocessing for 
particular functions. Every device driver must create a function 
decision table containing three or more entries: 


e The list of valid I/O function codes 
e The list of buffered I/O function codes 


e One or more entries, each of which specifies all or a_ subset 
of I/O function codes and the address of a routine that 
performs I/O preprocessing for those function codes 


If no buffered I/O functions are defined for the device, the second 
entry contains an empty list. 


Taken together, the third through last entries in the _ function 
decision table specify one or more FDT routines for each valid I/0 
function code for the device. It is the responsibility of the FDT 
routines to terminate the I/O preprocessing for each type of function 
by transferring control out of the Queue I/O Request system service 
and into a- routine that queues the I/O request to a driver, inserts 


the I/O request in the postprocessing queue, or aborts the _ I/0 
request. 


Refer to Chapter 8 for information on the coding of FDT routines. 


Table 7-1 lists the physical, logical, and virtual I/O function codes 
that a function decision table can specify. 


Physical codes 


Logical codes 


Virtual codes 


irrelevant to the device. 


function they represent. 
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Table 7-1 
VAX/VMS I/0 Function Codes 


CO NARM ARRANGE OAARIAERA +s nan Ab beanmnne yaa apap nama sf meme i earn: tui 


Type of Function 


FARR le trent AMR ene: iad mde, 








IOS DIAGNOSE 
IO0$ DRVCLR 

I0$ ERASETAPE 
IOS NOP 

IO$_ OFFSET 

IO$ PACKACK 

IO0$ READHEAD 
IO$ READPBLK 
I0$ READPRESET 
IO$ READTRACKD 
IOS RECAL 

I0$ RELEASE 

IOS RETCENTER 
I0$ SEARCH 

IO0$ SEEK 

IOS SENSECHAR 
IOS SETCHAR 

IOS SPACEFILE 
I0$ SPACERECORD 
IOS STARTSPNDL 
10$ UNLOAD 

IOS WRITECHECK 
IO$_WRITECHECKH 
IO0$ WRITEHEAD 
10S” WRITEMARK 
I0$ WRITEPBLK 
IO$ WRITETRACKD 





IOS READLBLK 
IO$ REWIND 

IOS REWINDOFF 
IOS SENSEMODE 
10S SETMODE 
IOS SKIPFILE 
IOS SKIPRECORD 
IO$ WRITELBLK 
IO$ WRITEOF 





IO0$ ACCESS 

IOS ACPCONTROL 
IO$ CREATE 

IOS DEACCESS 
IOS DELETE 

IOS MODIFY 

IO$ MOUNT 

I0$S READPROMPT 
IOS READVBLK 
I0$ WRITEVBLK 
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Codes Defined 


eat 


Diagnose 

Drive clear 

Erase tape 

No operation 

Offset read heads 

Pack acknowledge 

Read header and data 

Read physical block 

Read in preset 

Read track data 
Recalibrate drive 

Release port 

Return to center line 
Search for sector 

Seek cylinder 

Sense tape characteristics 
Set device characteristics 
Space files 

Space records 

Start spindle 

Unload drive 

Write check data 

Write check header and data 
Write header and data 
Write tape mark 

Write physical block 

Write track data 


Read logical block 
Rewind tape 

Rewind and set offline 
Sense tape mode 

Set mode 

Skip files 

Skip records 

Write logical block 
Write end of file 


Access file 

Miscellaneous ACP control 
Create file 

Deaccess file 

Delete file 

Modify file 

Mount volume 


Read terminal with prompt message 


Read virtual block 
Write virtual block 


Defining Device-Specific Function Codes 


You can also define device-specific function 
name of a device-specific function with the name of a function that is 
The selected codes should, however, 
virtual) that 
For example, the assembly code that 
defines three device-specific physical I/O function codes. 


(logical, physical, or 


codes by 
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is appropriate for the 
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I0$ STARTCLOCK=IO$_ERASETAPE ; Start hardware clock 
IO$ STOPCLOCK=I0$ OFFSET ; Stop hardware clock 
I0$ STARTDATA=IO$ SPACEFILE ; Start data acquisition 


The device driver creates a function decision table by invoking the 
FUNCTAB macro. Each invocation of the FUNCTAB macro creates a 2- or 
3-longword entry in the function decision table. The first two 
invocations create 2-longword entries because they specify only 
function codes; they do not specify an accompanying action routine. 


All subsequent invocations of the FUNCTAB macro must’ specify both 
function codes and the address of an action routine that is to perform 
preprocessing for those function codes. These invocations’ create 
3-longword entries. 


The Queue I/O Request system service processes entries in the order in 
which they appear in the function decision table. When a function 
code is present in more than one 3-longword entry, the system service 
sequentially calls every action routine specified for the function 
code until an action routine stops the scan by aborting, completing, 
or queuing an I/O request. 


7.3.2 Determining Those Functions that are Buffered I/0 


The second entry in a efunction decision table indicates’ those 
functions that are handled as buffered I/O operations. In selecting 
the functions that are to be buffered, the you should take _ the 
Following information into consideration: 


e Direct I/O is intended only for devices whose I/O operations 
always complete quickly. For example, although terminal I/0 
is fast, users can prevent the I/O operation from completing 
by uSing CTRL/S to halt the operation indefinitely; 
therefore, terminal I/O operations are buffered I/O. 


e Use of direct I/O requires that the process pages containing 


the buffer be locked in memory. Locking pages in memory 
increases the overhead of swapping the process that contains 
the pages. 


e Use of buffered I/O requires that the data be moved from the 
system buffer to the user buffer. Moving data requires 
additional time. 


e Routines that manipulate data before delivering it to the user 
(for example, a terminal interrupt service routine) cannot 
gain access to the data if direct I/0 is used. Therefore, 
transfers that require data manipulation must be buffered I/0. 


@e VAX/VMS handles the quotas differently for direct I/O and 
buffered I/0, as described in the VAX/VMS System Manager's 
Guide. 


e Generally, DMA devices use direct I/O, while programmed I/0 
devices use buffered I/O. 


Section 7.3.4 provides an example of the functions handled as buffered 
I/O operations. 
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7.3.3 FUNCTAB Macro 
The FUNCTAB macro creates the function decision table for a driver. 
Format 

FUNCTAB [action],codes 


action 
The address of an action routine to call during I/O preprocessing 
of the specified action code or codes. An action routine is 
specified only for the third through last entries of the table. 
The list of valid I/0 functions and the list of buffered I/O 
Functions have no associated action routine. 


codes 
The list of I/O function codes. The macro expansion prefixes 


each code specified with the string IOS ; for example, READVBLK 
expands to IOS READVBLK. 


7.3.4 Example of FUNCTAB Macro Use 
A sample function decision table follows: 
XX FUNCTABLE: > Function decision table 


FUNCTAB- ,- 
<READLBLK ,- 


Valid functions 
Read logical block 


e 
s 
READPBLK ,- ; Read physical block 
READVBLK ,- ; Read virtual block 
SENSEMODE,- ; Sense reader mode 
SENSECHAR,- ; Sense reader characteristics 
SETMODE,- s Set reader mode 
SETCHAR,- > Set reader characteristics 
> 
FUNCTAB ,7 ; Buffered I/O functions 
<READLBLK ,- ; Read logical block 
READPBLK ,- : Read physical block 
READVBLK ,- ; Read virtual block 
SENSEMODE,- : Sense reader mode 
SENSECHAR,- : Sense reader characteristics 
SETMODE,- : Set reader mode 
SETCHAR,- : Set reader characteristics 
> 


FUNCTAB XX READ,- 
<READLBLK ,- 
READPBLK ,- 
READVBLK ,- 
> 

FUNCTAB +EXESSETMODE,- > Set mode/characteristics 
<SETCHAR,- : Set reader characteristics 
SETMODE,- ; Set reader mode 
> 

FUNCTAB +EXESSENSEMODE, - ; Sense mode/characteristics 
<SENSECHAR,- : Sense reader characteristics 
SENSEMODE,- : Sense reader mode 
> 


Read functions 
Read logical block 
Read physical block 
Read virtual block 


=e “So ™e “Ye 


In the example above, the routine (named XX READ) called for ae read 
function is a driver routine. It appears later in the driver module. 
The routines EXESSETMODE and EXESSENSEMODE, preceded by plus signs (+) 
in the macro argument, are VAX/VMS routines that preprocess I/O 
requests for the device's set characteristics and sense mode 
functions. 
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CHAPTER 8 


CODING FDT ROUTINES 


The Queue I/O Request system service uses the driver's’ function 
deciSion table to determine which FDT routines to call. These FDT 
routines validate user-specified arguments in the I/0 request. 
VAX/VMS contains many device-independent FDT routines. Device drivers 
contain device-dependent FDT routines. 


A driver should call the VAX/VMS device-independent FDT routines 
whenever posSible. This practice encourages the use of well-debugged 
routines and minimizes driver size. 


8.1 CONTEXT FOR FDT ROUTINE EXECUTION 


The Queue I/O Request system service calls all FDT routines in the 
context of the process that requested the I/O operation. 
Characteristics of process context at the time of a call to an FDT 
routine are as follows: 


e Virtual addresses are mapped according to the process. page 
tables. This mapping allows FDT routines access’ to 
user-specified virtual addresses. 


e The process is executing in kernel mode because the Queue I/O 
Request system service call executes a Change Mode to Kernel 
instruction. 


e The process privileges remain unchanged. 
e Interrupt priority level is set to IPLS$ ASTDEL. Therefore, 
the process can be rescheduled but cannot’ receive ASTs. 


Paging can occur. 


e FDT routines cannot call system services or VAX-11 RMS 
services. 


8.2 REGISTERS PRESET FOR FDT ROUTINE EXECUTION 


The Queue I/O Request system service alSo sets up ae series of 
registers for the FDT routines before calling them. Table 8-1 lists 
the registers. 
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Table 8-1 
Registers Loaded by Queue I/O Request Service 
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RO | Address of the FDT routine being called 


R3 Address of the I/O request packet for the current 
I/O request 


R4 Address of the process control block (PCB) of the 
current process 


R5 Address of the unit control block of the device 
assigned to the user-specified process I/O channel 


R6 Address of the channel control block that describes 
the user-specified process I/O channel 


R7 Bit number of the user-specified I/O function code 


R8 Address of the current entry in the function 
decision table 


AP Address of the first function-dependent parameter 
specified in the user's request 





8.3 CONVENTIONS FOLLOWED BY FDT ROUTINES 


Because FDT routines are called by the Queue I/O Request system 
service and return to it or, in turn, call another VAX/VMS routine, 
they must follow certain conventions to preserve register content and 
the expected process context. 


8.3.1 Register Conventions 


FDT routines are responsible for preserving the contents of R3 through 
R8 across subroutine calls. FDT routines can use RO through R2 and R9 
through Rll without saving their previous contents. If an FDT routine 
needs to uSe R3 through R8, the routine can use the push and pop 
register instructions to save registers on the stack and later restore 
them. The following is an example. 


PUSHR #°“M<R3,R4,R5> : Save R3-R5 on the stack 


POPR #°M<R3,R4,R5> + Restore R3-R5 from the stack 
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8.3.2 Process Context Conventions 


The Queue I/O Request system service executes in the context of the 
process that issues the I/O request, but in kernel mode and at 
IPL$ ASTDEL. The Queue I/O Request system service expects FDT 
routines to preserve this context. Therefore, an FDT routine observes 
the following conventions: 


e It does not lower IPL below IPL$ ASTDEL. 


e If a routine raises IPL, it must lower IPL to IPLS ASTDEL 
before exiting. 


e It does not alter the stack without restoring its original 
State before exiting. 


e It must not call system services or VAX-11 RMS services 


e It must observe the register conventions described in the 
previous section. 


e It exits either by an RSB instruction to return control to the 
system service, or it issues a JMP instruction to one of the 
VAX/VMS routines described in Section 8.4. 


8.4 TRANSFERRING INTO AND OUT OF AN FDT ROUTINE 


To transfer control to an FDT routine, the Queve I/O Request’ system 
service loads the address of the FDT routine into a register and 
executes a jump to subroutine instruction, as follows: 


JSB (RO) 
Fach FDT routine chooses an exit path based on the following factors: 


e Whether another FDT routine needs to be called to perform 
additional function-specific processing 


e Whether an error is found in the I/O request 
e Whether the operation is complete 


e Whether the I/O operation requires and is ready for device 
activity 


Figure 8-1 illustrates the FDT processing loop in the Queue I/O 
Request system service. 


As illustrated in Figure 8-1, the FDT routines are responsible _ for 
transferring control out of the FDT processing loop and into a VAX/VMS 
routine that queues an I/O request packet or completes an I/O request. 
The Queue I/O Request system service does not know when to stop 
scanning the function decision table. Therefore, you should ensure 
that all valid function codes ina driver's function decision table 
eventually call an FDT routine that does not return to the Queue I/O 
Request system service. 


CODING FDT ROUTINES 








READ 
NEXT 
FDT ENTRY 





FUNCTION 
CODE 
MATCH? 


FDT ROUTINE 
RETURNS 











CALL 
FDT 
ROUTINE 


FDT ROUTINE EXITS 


QUEUE IRP, 
FINISH I/O, 
OR ABORT I/O 





Figure 8-1 Queue I/O Request Scan of a Function Decision Table 


8.4.1 Exit Methods 


An FDT routine can exit using any of the methods summarized in Table 
8-2. The first method returns to the Queue I/0 Request system 
service. All other methods jump to VAX/VMS routines that take the 
appropriate action. 


8.5 FDT ROUTINES FOR DIRECT I/0 


The VAX/VMS operating system provides two standard FDT routines” that 
are applicable for direct I/O operations: EXESREAD and EXESWRITE. 


When called by the driver, these routines completely prepare a direct 
I/O read or write request. Thus, a driver that uses these routines 
eliminates the need for its own device-specific FDT routines. 


EXESREAD and EXESWRITE are described in 8.7. 
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Table 8-2 
FDT Exit Methods 


Exit Method Result 


r EE 





service. The FDT routine returns to the 
system service because the routine knows 


that the function decision table 
contains a subsequent entry with the 
same function code bit set. AS a 


result, the system service calls another 
FDT routine. 


JMP G*EXESQIODRVPKT Transfers control to a VAX/VMS~ routine 
that queues an I/O packet to a driver. 

or The FDT routine uses this exit method if 

all preprocessing is complete, if no 

JMP G“EXESALTQUEPKT fatal errors are found in the 


specification of an I/O request, and if 
device activity is required to complete 
the I/O request. 


Once an FDT routine transfers control to 
either of these routines, no driver code 
that further processes the I/O request 
can refer to the process virtual address 
space. 


EXESQIODRVPKT is the standard method 
used to queue an I/O request for device 
activity. This routine initiates driver 
action only if the device unit is 
currently idle; that is, there is no 
I/O request being processed. If the 
device unit is busy, EXESQIODRVPKT 
queues the request to the unit so that 
the driver will process it when the unit 
becomes available. 


In contrast, EXESALTQUEPKT initiates 
driver action at a special driver entry 
point without regard for the device 
unit's activity status. This routine is 
called by drivers that can handle two or 
more I/O requests simultaneously. 


JMP G°EXESFINISHIO Transfers control to a VAX/VMS”~ routine 
that writes a quadword of final I/0 
Status from RO and Rl into the “I/O 
Status field of the I/O request packet 
(IRPSL MEDIA and IRPSL MEDIA+4). The 
routine then inserts the I/O request 
packet in the I/O postprocessing queue. 


An FDT routine that discovers a 
device-dependent error should always 
return status uSing EXESFINISHIO or 
EXESFINISHIOC,. The routine returns to 
the Queue I/O Request system service the 
two longwords of status contained in the 
I/O status block (if any) specified in 
the Queue I/O Request. 





(continued on next page) 
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Table 8-2 (Cont.) 
FDT Exit Methods 
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JMP G”EXESFINISHIOC Transfers control to a routine that 
performs the same functions as 
EXESFINISHIO except that this’ routine 
always clears the second longword of the 
final I/O status. 

JMP G*EXESABORTIO Transfers control to a VAX/VMS~ routine 
that aborts an I/O request. An FDT 


routine that discovers a 
device-independent error in an I/0 
request should always use this method of 
exit. The routine stores a longword of 
status in RO and returns this to the 
system service. Inability to gain 


access to a data buffer is an example of 
a device-independent error. 





Section 8.7 details the VAX/VMS routines summarized above. 


8.6 FDT ROUTINES FOR BUFFERED I/0 


Device drivers for buffered I/O operations must contain their own 
device-specific FDT routines. An FDT routine for buffered I/O must 
perform the following steps: 


e Confirm either read or write access to the user's buffer 


e Allocate a buffer in system space 


8.6.1 Checking the User's Buffer 


First the FDT routine calls EXESREADCHK or EXESWRITECHK to - confirm 
write or read access, respectively, to the user's buffer. Both of 
these routines write the transfer byte count into IRPSW BCNT. 
EXESREADCHK also sets IRPS$V FUNC’ in IRPSW STS to indicate that the 
function is a read. 7 ~ 


8.6.2 Allocating the System Buffer 


Next, the FDT routine allocates a system buffer. First, it adds 12 
bytes for a buffer header to the byte count passed in the P2 parameter 
of the user's I/O request. This is the total system buffer size. The 
FDT routine then calls EXESBUFFROQUOTA to ensure that the user has 
sufficient remaining resources. If EXESBUFFRQUOTA returns with a 
success code, the FDT routine calls EXESALLOCBUF which allocates the 
buffer and writes the buffer's size and type into its third longword. 
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Once the buffer is allocated, the FDT routine takes the following 
steps: 
e Loads the address of the system buffer into IRPSL SVAPTE 
e Loads the total size of the system buffer into IRPSW_BOFF 
e Subtracts the system buffer size from JIBSL BYTCNT. A 
longword in the PCB points to the location of the Job 
Information Block (JIB). 


e Stores the starting address of the system buffer data area in 
the first longword of the buffer header 


e Stores the user's buffer address in the second longword of the 
header 


e Copies data from the user buffer to the system buffer if the 
I/O request is a read operation 


At this point, buffers are ready for the transfer. Figure 8-2 
illustrates the format of the system buffer. 


SYSTEM BUFFER 





ADDRESS OF DATA AREA 
USER BUFFER ADDRESS 
TYPE SIZE 







HEADER 









BUFFER 
DATA 
AREA 





USER 
BUFFER 


Figure 8-2 Format of System Buffer for Buffered I/O Read Operations 


Appendix C provides additional information about EXESREADCHK, 
EXESWRITECHK, EXESBUFFRQUOTA, and EXESALLOCBUF. 


8.6.3 Completion of Buffered I/O in I/0 Postprocessing 


When the transfer finishes, the driver returns control to VAX/VMS_ for 
completion of the I/O request. The driver writes the final count of 
bytes transferred into the high-order word of RO and the final request 
status in the low order words of RO and Rl. The driver must leave the 
buffer header intact; I/O postprocessing relies on the header's 
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accuracy. When VAX/VMS I/O postprocessing gains control, it performs 
the following steps: 


e Adds the value in IRPSW_BOFF to JIBSL BYTCNT to update the 
user's byte count quota 


e If IRPSL SVAPTE is nonzero, assumes a system buffer was 
allocated and checks to see whether IRPSV FUNC is set in 
IRPSW_STS 7 

e If IRPSV FUNC is clear, deallocates the system buffer used for 
the write operation; if IRPSV FUNC is set, the kernel mode 
AST copies the data to the user's buffer and then deallocates 
the buffer in addition to performing other kernel mode AST 
functions 


The kernel mode AST performs the following steps to complete a 
buffered read operation: 


e Obtains the address of the system buffer from IRPSL_SVAPTE 


e Obtains the number of bytes to write to the user's buffer from 
IRPSW_BCNT (for a read operation) 


e Obtains the address of the user's buffer from the second 
longword of the system buffer header 


e Checks for write accessibility on all pages of the user's 
buffer (for a read operation) 


e Copies the data from the system buffer to the process's buffer 
(for a read operation) 


e Deallocates the system buffer. Note that the system uses’- the 
size listed in the buffer's header to deallocate the buffer. 


8.7 FDT ROUTINES PROVIDED BY VAX/VMS 
The VAX/VMS FDT routines perform I/O request validation that is common 
to many devices. Whenever possible, drivers should take advantage of 
these routines. Normally, if a VAX/VMS FDT routine is called, no 
additional FDT processing is required. All of the VAX/VMS FDT 
routines described here exit by transferring control to one of the 
Following VAX/VMS routines: 

@e EXESQIODRVPKT 

e@ EXESALTQUEPKT 

e EXESFINISHIO 

@e EXESFINISHIOC 

e EXESABORTIO 


Once a VAX/VMS FDT routine is called, no subsequent FDT processing 
occurs. 


For information about additional FDT routines, see Appendix C. 
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8.7.1 EXESONEPARM 


EXESONEPARM processes an I/O function code that has one parameter 
associated with it. 


Exit Method 
Queues the I/O request packet to the driver. 
Description 


Processes an I/O function code that requires only one parameter 
that needs no checking; for example, the parameter does not have 
to be checked for read or write accessibility. EXESONEPARM 
stores the parameter, found at O(AP), in IRPSL MEDIA of the I/0 
request packet. Then, it queues the I/O request packet to the 
driver. 


8.7.2 EXESREAD 


EXESREAD processes a logical or physical read function code for a 
Girect I/O operation. EXESREAD cannot be used _ for buffered I/0 
operations. 


Exit Method 


Aborts the I/O request if an error occurs, or dismisses and 
resubmits the I/O request if the user I/O buffers cannot be 
locked in memory; otherwise, queues the I/O request packet to a 
driver. 


Description 


Sets the I/O function bit in the status field (IRPSV_FUNC in 
IRPSW STS) of the I/O request packet. This bit indicates that 
the function is a read. 


EXESREAD writes the fourth parameter, located at 12(AP) into the 
carriage control field (IRPSB CARCON). 


The routine replaces the logical function code I0$ READLBLK with 
the physical function code IOS READPBLK in the function code 
field (IRPSW_ FUNC) of the I/O request packet. 


If the second parameter (the transfer byte count) 1s ‘Zé6éro, 
EXESREAD queues’ the I/O request packet to a device driver. The 
second parameter is found at 4(AP). If the byte count is not 
zero, EXESREAD uses the starting address of the transfer, found 
at O(AP), and the transfer byte count as arguments to the routine 
EXESREADLOCK. 


The routine EXESREADLOCK calls EXESREADLOCKR, which immediately 
calls EXESREADCHKR. This last subroutine determines whether the 
caller's buffer permits write access, 


If EXESREADCHKR finds that the buffer is accessible, it updates 
the I/O request packet by writing the size in bytes of the 
transfer to IRPSW BCNT and setting the read status bit in 
IRPSW STS (IRPSV FUNC). The maximum number of bytes” that 
EXESREAD can transfer is 65536 (128 pages). 
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If the buffer does not allow write access, EXESREADCHKR'- returns 
access violation status to its caller, EXESREADLOCKR, which 
summons its caller (EXESREADLOCK) as a coroutine. 


When EXESREADLOCK is called as a coroutine, it does not take any 
error action. Instead, it passes control to EXESREADLOCKR, which 
aborts the queue I/O request with access violation status. 
EXESREADLOCK is called as a coroutine for the convenience of 
drivers that call EXESREADLOCKR directly. See Appendix C_ for 
more details. 


After EXESREADCHKR confirms the buffer's write accessibility, 
EXESREADLOCKR calls the routine MMGSIOLOCK to lock into memory 
those pages that contain the buffer. MMGSIOLOCK, can return 
Success, page fault, or error status to EXESREADLOCKR. 


If MMGSIOLOCK succeeds, EXESREADLOCKR stores the address of the 
process page table entry (PTE) in the field IRPSL SVAPTE and 
returns Success status to EXESREADLOCK. 


However, if MMGSIOLOCK reports a page fault, EXESREADLOCKR 
adjusts direct I/O count and AST count to the values they held 
before the I/O request, deallocates the I/O request packet’ and 
restarts the request procedure at the Queue I/O Request system 
service. This procedure is carried out so that the user’ process 
can receive asynchronous system traps while it waits for the page 
fault to complete. Once the page is faulted into memory, the 
system service will resubmit the queue I/O request. 


MMGSIOLOCK can report either of two’ errors: access violation 
(SS$ ACCVIO) and insufficient working set limit (SSS INSFWSL). 
When EXESREADLOCKR receives an error, it aborts the request with 
error status. 


After EXESREADLOCK returns to EXESREAD, the routine passes 
control to the exit routine EXESQIODRVPKT so that the request is 
queued to the driver. 


8.7.3 EXESSENSEMODE 
EXESSENSEMODE processes the sense device mode and characteristics 
function by reading fields of the unit control block. No device 
activity occurs. 
Exit Method 
Transfers control to EXESFINISHIO. 
Description 
Loads the device-dependent characteristics field 
(UCBSL_DEVDEPEND) of the unit control block into Rl. 
EXESSENSEMODE then loads a normal completion status (SSS NORMAL) 


into RO. Finally, it transfers control to EXESFINISHIO to insert 
the I/O request packet in the I/O postprocessing queue. 
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8.7.4 EXESSETCHAR 


EXESSETCHAR processes the set device mode and characteristics 
function. If setting device characteristics requires no device 
activity or requires no synchronization with fork processing, the 
driver's FDT entry can specify EXESSETCHAR; otherwise, it must 
specify EXESSETMODE. 


Exit Method 


Aborts the I/O request on error; otherwise, transfers control to 
EXESFINISHIO. 


Description 


Determines whether the process has read access to the quadword 
that describes the new characteristics for the device. The first 
parameter, found at O(AP), specifies the address of the quadword. 
If the process does not have read access’ to the quadword, 
EXESSETCHAR aborts the request. 


If the process has read access, EXESSETCHAR stores the new 
characteristics in fields of the device's unit control block. If 
the function is IOS SETCHAR, the device type and class’ fields 
(UCBSB DEVCLASS and UCBSB DEVTYPE, respectively) of the unit 
control block receive the first word of data addressed by the 
parameter. 


For both the IO$ SETCHAR and I0$ SETMODE functions, the routine 
writes the second word of data into the UCB default buffer size 
field (UCBSW DEVBUFSIZ) and the third and fourth words of data 
into the device-dependent characteristics field 
(UCBSL DEVDEPEND). 


Finally, EXESSETCHAR stores’ the normal completion status 
(SSS NORMAL) in RO and transfers control to EXESFINISHIO to 
insert the I/O request packet in the I/O postprocessing queue. 


8.7.5 EXESSETMODE 


EXESSETMODE processes the set device mode and characteristics 
Functions by activating the device. 


Exit Method 


Aborts the I/O request if an error occurs; otherwise, queues the 
I/O request packet to the device driver. 


Description 


Determines whether the process has read access to the quadword 
that describes the new characteristics for the device. The first 
parameter, found at O(AP), specifies the address of the quadword. 
If the process does not have read access to the quadword, 
EXESSETMODE aborts the request. 


If the process has read access, EXESSETMODE stores the new 
characteristics in the media field (IRPSL MEDIA and 
IRPSL MEDIA+4) of the I/O request packet. The routine’ then 
transfers control to the exit routine EXESQIODRVPKT, which queues 
the request to the appropriate device driver. 
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8.7.6 EXESWRITE 


EXESWRITE processes a logical or physical write function code for a 


direct I/O operation. EXESWRITE cannot be used for buffered I/O 
operations. 


Exit Method 


Aborts the I/O request if an error occurs, or dismisses the I/0 
request if the user I/0 buffers cannot be locked in memory; 
otherwise, queues the I/O request packet to a driver. 


Description 


Writes the fourth parameter, found at 12(AP) into the I/O request 
packet's carriage control field (IRPSB CARCON). 


EXESWRITE replaces the logical function code IOS WRITELBLK with 
the physical function code IOS WRITEPBLK in the function code 
field of the I/O request packet (IRPSW FUNC). 


If the second parameter (the transfer byte count) iS zero, 
EXESWRITE queues the I/O request packet to the driver. The 
second parameter is found at 4(AP). If the byte count is not 
zero, EXESWRITE uses the starting address of the transfer, found 
at O(AP), and the transfer byte count aS arguments to the routine 
EXESWRITELOCK. 


The routine EXESWRITELOCK calls EXESWRITELOCKR, which immediately 
calls EXESWRITECHKR. This last subroutine determines whether the 
caller's buffer permits read access. 


If EXESWRITECHKR finds that the buffer is accessible, it updates 
the I/O request packet by writing the size in bytes of the 
transfer to IRPSW BCNT. EXESWRITE can transfer a maximum of 
65536 bytes (128 pages). 


If the buffer does not allow read access, EXESWRITECHKR' returns 
access violation status to its caller, EXESWRITELOCKR, which 
Summons its caller (EXESWRITELOCK) as a coroutine. 


When EXESWRITELOCK is called as a coroutine, it does not take any 
error action. Instead, it passes control to EXESWRITELOCKR, 
which aborts the queue I/O request with access violation status. 
EXESWRITELOCK is called as a coroutine for the convenience of 
drivers that call EXESWRITELOCKR directly. See Appendix C_ for 
more details. 


After EXESWRITECHKR confirms the buffer's read accessibility, 
EXESWRITELOCKR calls the routine MMGSIOLOCK to lock into memory 
those pages that contain the buffer. MMGSIOLOCK can return 
success, page fault, or error status to EXESWRITELOCKR. 


If MMGSIOLOCK succeeds, EXESWRITELOCKR stores the address of the 
process page table entry (PTE) in IRPSL SVAPTE and returns 
success Status to EXESWRITELOCK. 


However, if MMGSIOLOCK reports a page fault, EXESWRITELOCKR 
adjusts direct I/0 count and AST count to the values they held 
before the I/O request packet and restarts the request procedure 
at the Queue I/O system service. The routine carries out this 
procedure so that the user process can receive ASTS while it 
waits for the page fault to complete. Once the page is faulted 
into memory, the system service will resubmit the queue I/0 
request. 
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MMGSIOLOCK can report either of two errors: access violation 
(SS$_ACCVIO) and insufficient working set limit (SS$_INSFWSL). 
When EXESWRITELOCKR receives an error, it aborts the request with 
error status. 


After EXESWRITELOCK returns to EXESWRITE, the routine passes 
control to the exit routine EXESQIODRVPKT so that the request is 
queued to the driver. 


8.7.7 EXESZEROPARM 


EXESZEROPARM processes an I/O function code that has no _ associated 
parameters. 


Exit Method 
Queues the I/O request packet to the driver. 
Description 


Processes an I/O function code that describes an I/O operation 
completely without any additional function-specific parameters. 
The only FDT processing necessary for a zero parameter function 
code is to zero-fill the field of the I/O request packet that 
normally contains a user-specified parameter (IRPSL MEDIA). Then 
EXESZEROPARM queues the I/O request packet to a device driver. 


8.8 EXIT ROUTINES IN THE VAX/VMS SYSTEM 


Ultimately, FDT processing must terminate by transferring control to 
one of the following VAX/VMS routines: EXESABORTIO, EXESFINISHIO, 
EXESFINISHIOC, EXESALTQUEPKT, or EXESQIODRVPKT. Each of these 
routines returns the system service status code to the user. 


8.8.1 EXESABORTIO 


When an FDT routine determines that an I/O request cannot be completed 
because of an error in the specification of the request or in FDT 
processing, the FDT routine transfers control to the VAX/VMS~ routine 
EXESABORTIO to abort the request. EXESABORTIO gains control without 
any change in the process context. Interrupt priority level is at 
IPLS ASTDEL; the process virtual space is mapped; and the process is 
executing in kernel mode. 


Required Register Contents 


RO Queue I/O Request system service final status code 

R3 Address of the current I/O request packet 

R4 Address of the process control block of the current 
process 

R5 Address of the unit control block of the device unit 


assigned to the process I/O channel 


R3 through R5 always contain the I/O request packet, PCB, and UCB 
addresses at the entry to an FDT routine. The FDT routine should 
be careful not to destroy these values. 
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Description 


EXESABORTIO clears the address of the I/O status block in the I/0 
request packet (IRPSL IOSB) so that no status will be returned 
during I/O postprocessing. EXESABORTIO also clears the bit in 
the I/O request packet (ACBSV_ QUOTA in the field IRPSB_RMOD). 
When set, this bit indicates that the requesting process 
specified an AST routine. If necessary, the routine readjusts 
the process's use of its AST quota. 


Then EXESABORTIO inserts the I/O request packet in the I/0 
postprocessing queue. If no other entries are in the queue, 
EXESABORTIO requests a software interrupt at IPLS IOPOST. This 
interrupt causes postprocessing to occur before any other 
instructions in the EXESABORTIO routine are executed. 


When all I/0 postprocessing has been completed, EXESABORTIO 
regains control and finishes the I/O operation as follows: 


e Lowers IPL to zero, which is the normal IPL for a process 
e Changes mode back to the original processor access mode 


e Returns from the system service to the code of the image that 
originally requested the I/O operation. EXESABORTIO returns 
RO, which contains the final status code saved when the exit 
routine was called, to its caller. 


As a result of this exit method, any ASTs specified when the 
I/O request was issued will not be delivered, and any event 
flags requested will not be Set. 


8.8.2 EXESFINISHIO and EXESFINISHIOC 


Many I/O requests need no device activity to be completed. The FDT 
routine(s) can complete the entire I/O request and immediately return 
status concerning the operation to the process. However, the VAX/VMS 
operating system provides two VAX/VMS I/0 completion routines: 
EXESFINISHIO and EXESFINISHIOC. EXESFINISHIO returns a quadword of 
I/O status. EXESFINISHIOC returns a quadword of I/O status with the 
second longword containing zero. 


These routines gain control without any change in process’ context. 
Interrupt priority level is at IPLS$ ASTDEL; the process page tables 
are mapped; and the process is executing in kernel mode. 


Required Register Content 
RO Value to be placed in the first longword of final I/0 


status when the Queue I/O Request system Service returns 
final status 


Rl Value to be placed in the second longword of final I/O 
Status (EXESFINISHIO only) 

R3 Address of the current I/O request packet 

R4 Address of the process control block of the current 
process 

R5 Address of the unit control block of the device unit 


assigned to the process I/O channel 


R3 through R5 always contain the I/O request packet, PCB, and UCB 
addresses at the entry to an FDT routine. The FDT routine should 
be careful not to destroy these values. 
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Description 


EXESFINISHIO and EXESFINISHIOC modify fields in the I/O data base 
and then complete the I/O request in the following steps: 


e Increase the number of I/0 operations completed on the current 
device in the operation count field of the unit control block 
(UCBS$L_OPCNT) 


e Store the contents of RO and R1 in the media fields of the I/O 
request packet (IRPSL MEDIA and IRPSL MEDIA+4) 


e Insert the I/O request packet in the I/O postprocessing queue 
and, if the queue is empty, request a software interrupt 


The software interrupt occurs at IPL 3 so that postprocessing 
interrupts EXESFINISHIO or EXESFINISHIOC. When EXESFINISHIO or 
EXESFINISHIOC regains control, it completes processing in the 
following steps: 


e Lowers IPL to zero, which is the normal IPL for a process 
e Changes mode back to the original processor access mode 


e Returns from the system service to the code of the image that 
originally requested the I/O operation. The image receives 
status SSS NORMAL in RO, indicating that the queue I/O request 
has completed without device-independent error. 


8.8.3 EXESQIODRVPKT 


Some I/O functions require device activity, or at least access to 
device registers, for the I/0 operation to be completed. Common 
examples are read and write functions. The FDT routineS can perform 
extensive preprocessing, such as determining whether user buffers are 
accessible and reformatting data into buffers in the system address 
space, but they should not access device registers because the device 
might be active. By convention, FDT routines do not modify the unit 
control block or device register contents for reasons) of 
synchronization. FDT routines do not execute at the proper IPL (fork 
IPL) to make such modifications. As a result, they could crash the 
system or cause their driver to execute incorrectly. 


For this type of I/O function, the associated FDT routines perform all 
preprocessing and then transfer control to the VAX/VMS~ routine 
EXESQIODRVPKT. It queues the I/O packet to a device driver and 
attempts to transfer control to the device driver's start I/O routine. 
If the device unit is busy, EXESQIODRVPKT inserts the I/O request 
packet in a priority-ordered queue of packets waiting for the unit. 


Required Register Contents 


R3 Address of the I/O request packet 
R4 Address of the process control block of the current process 
R5 Address of the unit control block for the device unit 


assigned to the process I/O channel 
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Description 


EXESQIODRVPKT calls EXESINSIOQ, which first raises the interrupt 
priority level of the process to the fork level of the driver 
(UCBSB FIPL). Driver fork level is, by convention, the interrupt 
priority level at which device drivers and VAX/VMS read and alter 
Critical portions of the device's unit control _ block. By 
executing at fork level, EXESINSIOQ ensures that, while it is 
running, a driver fork process for the device unit cannot also be 
running. 


EXESINSIOQ tests the UCB status word to see if the unit is busy. 


If the device unit is not busy, EXESINSIOQ calls the VAX/VMS 
routine IOCSINITIATE to create a fork process context in which 
the driver can process the I/O request. IOCSINITIATE creates 
this context and activates the driver in the following steps: 


e Sets the busy bit of the device's unit control block 
(UCBSV_BSY in UCBS$W_STS) 


e Stores the address of the current I/O request packet in the 
UCB field UCBSL_IRP 


e Copies the transfer parameters contained in the I/O request 
packet into the unit control block: 


~ Copies the Starting address from IRPSL_ SVAPTE to 
UCBS$L_SVAPTE 


- Copies the byte offset within the page from IRPSW_BOFF to 
UCBSW_BOFF 


- Copies the byte count from IRPSW_BCNT to UCBSW_BCNT 


e Clears the cancel I/O and timeout bits in the UCB status word 
(UCBSV_CANCEL and UCBSV_TIMOUT in UCBSW_STS) 


e If the I/O request specifies a diagnostic buffer, as indicated 
by the bit IRPSV DIAGBUF in IRPSW STS, stores the system time 
in the buffer (IRPSL DIAGBUF); (the Queue I/O Request system 
service has already allocated the buffer) 


e Finds the entry point of the device driver's start I/O routine 
using the following chain of pointers: 


UCB —™DDB —=»DDT — start I/O entry point 


e Transfers control to the driver start I/O routine using a JMP 
instruction 


If, on the other hand, EXESINSIOOQ finds that the device is busy, 
it inserts the I/O packet in the device unit's I/O request packet 
wait queue for processing later. The I/O request packet wait 
queue is ordered by two factors: 


e The time that the entry is queved; that is, within any given 
priority the gqueve is first-in/first-out 


e The priority of the I/O request packet, which is derived from 
the requesting process's base priority and stored in the field 
IRPSB_ PRI 
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EXESINSIOQ calls the VAX/VMS routine EXESINSERTIRP to insert the 
I/O request packet in the unit's I/O request packet queue. Then, 
EXESINSIOQ reduces the interrupt priority level to the level at 
the beginning of itS execution; that is, to IPLS ASTDEL. 
EXESINSIOQ returns control to EXESQIODRVPKT. Finally, 
EXESQIODRVPKT returns from the Queue I/O Request system service 
in the following steps: 


e Loads a success status code (SSS_NORMAL) into RO 
e Reduces the interrupt priority level to 0 


e Changes mode to the access mode of the process at the time of 
the I/O request by issuing an REI instruction 


e Returns from the system service call 


The system sets and clears the busy bit in the UCB status word for the 
device unit. This bit prevents the driver from being called to 
service a device unit that is already engaged in another I/O request. 


When a device driver's start I/O routine gains control, the process 
that queued the I/0 request may no longer be the mapped process. 
Therefore, the driver must assume that all information regarding the 
I/O request is in the unit control block or the I/O request packet and 
that all buffer addresses in the unit control block are either system 
addresses or page frame numbers that can be interpreted in any process 
context. For direct I/O operations, FDT routines also must have 
locked all user buffer pages in physical memory since paging cannot 
occur at driver fork level and higher interrupt priority levels. The 
process virtual address space is not guaranteed to be mapped again 
until VAX/VMS delivers a kernel mode AST to the requesting process as 
part of I/O postprocessing. 


8.8.4 EXESALTQUEPKT 


Special purpose drivers may want to use their own internal I/O queues 
as well as the device unit I/0 queue (UCBSL IOQFL) provided by 
VAX/VMS. These internal queues allow the driver to handle I/0 
requests even if the device is busy with another I/O operation. 


EXESALTQUEPKT permits the driver to ignore unit I/O queue 
synchronization. When called by an FDT routine, EXESALTQUEPKT gains 
access to the driver at the alternate start I/O entry point specified 
in the driver dispatch table (offset DDTSL ALTSTART). This entry 
point bypasses the unit I/O queue and the device busy flag; thus, the 
driver is activated regardless of whether the device unit is busy. 


A driver that uses EXESALTQUEPKT becomes responsible not only for its 
internal queues but also for any synchronization between those queues 
and the unit I/O queue maintained by the operating system. 


Drivers complete I/O request packets obtained from EXESALTQUEPKT by 
calling the routine COMSPOST. This routine places the I/O request 
packet in a postprocessing queue and returns control to the driver. 
The driver may then fetch another packet from an internal queue. 


If a driver processes more than one I/O request packet at the same 
time, separate fork blocks must be used. 


Be aware that programming a device driver to process simultaneous’ I/0 
requests requires detailed knowledge of VAX/VMS internal design. 
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Required Register Contents 


R3 Address of the I/O request packet 
R5 Address of the unit control block 


You must asSume that the contents of RO through R5 are destroyed 
upon return to the FDT routine. 


Description 
EXESALTQUEPKT performs the following steps: 
e Saves the current interrupt priority level on the stack 


e Raises interrupt priority level to driver fork level 
(UCBSB FIPL). 


e Finds the entry point of the alternate start I/O routine using 
the following chain of pointers: 


UCB —=™ DDB —= DDT —» alternate start I/O address. 
e Calls the driver at alternate Start I/O address. 


When the alternate start I/O routine finishes, it returns control _ to 
EXESALTQUEPKT by executing an RSB instruction. EXESALTQUEPKT restores 
the interrupt priority level saved on the stack and then returns 
control to the FDT routine that called it. The FDT routine then 
executes a JMP instruction to the routine EXESQIORETURN in order’ to 
return control to the uSer process. 


CHAPTER 9 


CODING THE START I/O ROUTINE 


A driver start I/O routine activates a device and then waits for a 
device interrupt or timeout. This chapter describes the start I/0 
routine. Chapter 12 describes the reactivation of the driver routine 
that performs device-dependent I/0 postprocessing. The start I/O 
routine discussed in the following sections describes a DMA transfer 
using a single-unit controller. 


9.1 TRANSFERRING CONTROL TO START I/O 


The start I/O routine of a device driver gains control from either of 
two VAX/VMS routines: EXESQIODRVPKT or IOCSREOCOM. 


When FDT processing is complete for an I/O packet, the FDT routine 
transfers control to EXESQIODRVPKT. If the designated device is idle, 
IOCSINITIATE is called to create a driver fork process. (This 
procedure is detailed in Section 8.7.3.) The driver fork process then 
gains control in the start I/O routine of the appropriate driver. If 
the device is busy, EXESQIODRVPKT queues the packet to a device unit's 
I/O request packet wait queue. 


After a device completes an I/O operation, the driver fork process 
exits by transferring control to IOCSREQCOM. IOCSREQCOM inserts the 
finished I/O packet in the postprocessing queue. It then dequeues the 
next I/O request packet from the device unit's I/O request packet wait 
queue and calls IOCSINITIATE to create a new driver fork process” that 
gains control at the entry point of the driver's start I/O routine. 


9.2 CONTEXT OF A DRIVER FORK PROCESS 


A start I/O routine does not run in the context of a user. process. 
Rather, it has the following context: 


System mapping Only system page tables are mapped. 
Therefore, driver code cannot refer to 
virtual addresses in process address space. 


Kernel mode Execution occurs in the most privileged 
access mode and can, therefore, change IPL. 


High IPL The VAX/VMS routine that creates a driver 
fork process raises IPL to driver fork level 
before activating the driver. The driver can 
raise and lower IPL between driver fork level 
and IPLS POWER. 
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Kernel or Execution occurs on the kernel or interrupt 

interrupt stack stack. The driver must not alter the state 
of the stack without restoring it to its 
previous state before relinquishing control. 


The start I/O routine executes on the kernel stack if the VAX/VMS 
packet queuing routine activated the start I/O routine. It executes 
on the interrupt stack if the VAX/VMS- request complete routine 
activates the start I/O routine. 


In addition to the context described, the VAX/VMS packet queuing 
routine sets up R3 and R5 for a driver start I/O routine, as follows: 


e R3 contains the address of the I/O request packet. 


e R5 contains the address of the unit control block for’ the 
device. 


All registers must be preserved except for RO, Rl, R2 and R4. 


The packet queuing routine also copies the following I/O request 
packet fields into the UCB: 


® IRPSW_BCNT 
e IRPSW_ BOFF 


e IRPSL SVAPTE 


9.3 ACTIVATING THE DEVICE 


The processing performed by a start I/O routine is device-specific. A 
Start I/O routine normally contains elements to perform the following 
functions: 


e Analyze the I/0 function 


e Transfer the details of a transfer from the I/O request packet 
into the unit control block 


e Obtain and initialize the controller and, for DMA transfers, 
UNIBUS adapter resources 


e Modify device registers to activate the device 


The start I/O routine elements listed above execute a series of steps 
to activate the device. The sections that follow describe those steps 
as performed for a sample DMA device such as a parallel communications 
link; the details of processing, however, are specific to the 
particular device. UNIBUS-related details of DMA transfers are 
described in Chapter 10. 


9.3.1 Obtaining Controller Access 


If the device is attached to a multiunit controller, the start I/0 
routine invokes the VAX/VMS macro REQPCHAN to assign the controller 
data channel to the device unit. Single-unit controllers do not 
require arbitration for the controller data channel. REQPCHAN calls 
the VAX/VMS routine IOCSREQPCHANL that acquires ownership of the 
controller data channel. 


CODING THE START I/O ROUTINE 


The transfer being controlled by the start I/O routine discussed here 
requires no seek preceding the transfer. Disk I/O is an example of a 
transfer that requires a seek first. To permit seeks to be overlapped 
with transfers, invoke REQPCHAN with the argument PRI=HIGH. 
Specifying PRI=HIGH inserts a request for a channel at the head of the 
channel wait queue. 


If the channel is not available, IOCSREQPCHANL suspends’ driver 
processing by saving the driver's context in the UCB fork block and 
inserting the fork block address in the channel wait queue. 
ITOCSREQPCHANL then returns control to the caller of the driver, that 
is, to IOCSINSIOQ, as illustrated in Figure 9-1. 


The UCB fork block now represents the entire context of the suspended 
driver: 


e Saved R3 containing the address of the I/O request packet 
e Implicit saved R5 containing the UCB address 
e A return address in the driver 


IOCSREQPCHANL does not save R4 since it writes R4 before returning 
control to the driver. 
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Figure 9-1 Driver Insertion into Channel Wait Queue 


If the channel is available, IOCSREQPCHANL locates the interrupt data 
block for the channel with a pointer in the unit control block: 


UCB —» CRB —» IDB 


The interrupt data block contains the address of the control/status 
register for the channel (IDBSL CSR). IOCSREQPCHANL returns the 
control/status register address in R4. The driver for a unit attached 
to a single-unit controller must contain the code needed to load the 
control/status address into R4. 
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IOCSREQPCHANL also writes the UCB address of the new channel owner’ in 
the owner field of the interrupt data block (IDBSL OWNER). The driver 
interrupt service routine later reads this IDB field to determine 
which device unit owns the controller data channel. A driver for a 
Single-unit controller must fill the IDBSL OWNER field in its 
controller or unit initialization routine. = 


The driver must maintain the stack in a known and consistent state for 
the resource wait queue mechanism to work. When IOCSREQPCHANL gains 
control, the top two items on the stack must be two return addresses: 


e O(SP) -- Address of the next instruction to be executed in the 
driver fork process 


e 4(SP) -- Address of the next instruction to be executed in the 
routine that called the driver start I/O routine 


9.3.2 Getting the I/O Function Code and Converting the Code and Modifiers 


The start I/O routine extracts the I/O function code and function 
modifiers from the field IRPSW FUNC and translates them into 
device-specific function codes to be loaded into the device's 
control/status register or other control registers. The I/O routine 
being described in this chapter sets up a bit mask that is to be 
modified further in subsequent instructions and loaded into the 
control/status register when the driver actually starts the device. 
That is, the start I/0 routine converts the function modifiers 
contained in IRPSW FUNC into device-specific bit settings in the 
general register (R3 in this case). 


9.3.3 Obtaining a Buffered Data Path 


If the device uses a buffered data path, the start I/O routine invokes 
the VAX/VMS macro REQDPR to allocate the data path; Chapter 10 
provides the details of interfacing with the UNIBUS adapter, including 
a description of the REQDPR macro. REQDPR calls the VAX/VMS routine 
IOCSREQDATAP, which allocates a data path if one is available. 


If no buffered data path is available, IOCSREQDATAP suspends’ driver 
processing by saving the driver's context in the UCB fork block and 
inserting the fork block address in the data path wait queue. 
IOCSREQDATAP then returns control to the caller of the driver. 


If a buffered data path is available, IOCSREQDATAP writes the number 
of the data path allocated to the driver into the channel request 
block at CRB$L INTD+VECS$B DATAPATH. 


If the device uses a direct data path, no data path allocation is 
required. The direct data path is the default data path as long as no 
code has ever written a nonzero value into the CRB data path field. 


9.3.4 Loading Map Registers 


The driver's start I/O routine invokes the VAX/VMS macro LOADUBA to 
load the page frame numbers’ of the physical pages involved in the 
transfer into the allocated map _ registers. The macro calls’7 the 
VAX/VMS routine IOCSLOADUBAMAP, as described in Chapter 10. Using the 
byte offset and byte count fields of the unit’ control block 
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(UCBSW BOFF and UCBSW BCNT, respectively), IOCSLOADUBAMAP computes the 
number of map registers to load. It then obtains the number of the 
first page frame number from the page table entry field of the unit 
control block (UCBSL_ SVAPTE). 


In each map register, IOCSLOADUBAMAP sets the valid bit and fills in 
the information needed for the transfer, that is, data path number, 
physical page frame number, and an indication of whether the’ transfer 
is word aligned. For further information, refer to Section 10.3. 


9.3.5 Computing the Transfer Length 


Because the device driven by this particular driver expects’ the 
transfer as a word count, the start I/O routine computes the length of 
the transfer in words by dividing the byte count field of the unit 
control block (UCBSW BCNT) by 2. The routine loads the computed value 
into the word count device register. One of the FDT routines’ that 
processes the I/O request must ensure that the byte count for the 
transfer is even. An odd byte count results in the user's not 
receiving the last byte of data. 


9.3.6 Computing the Transfer Start Address 


The start I/O routine calculates the address of the transfer using the 
byte offset field of the unit control block (UCBSW BOFF) and the 
number of the starting map register (CRBSL INTD+VECSW MAPREG). The 
result is an 18-bit value representing an address in UNIBUS address 
Space. Section 10.4 details the calculation of the starting address 
for a UNIBUS transfer. 


The start I/O routine stores the low-order 16 bits of the computed 
value in the buffer address device register. It stores the two 
high-order bits of the computed value in the memory extension bits of 
the bit mask set up in Section 9.3.2 to contain the device 
control/status register data, in this case, R3. 


9.3.7 Preparing the Device Activation Bit Mask 


The start I/O routine prepares the device activation bit mask _ by 
setting the interrupt enable and go bits in the general register used 
previously (in this discussion, R3). The general register contains a 
complete command to start the transfer at this point. When the start 
I/O routine copies the contents of the register into the device's 
control/status register, the device starts the transfer. However, 
before activating the device, the start I/O routine should perform the 
steps described in Sections 9.3.8 and 9.3.9. 


9.3.8 Blocking All Interrupts 


The start I/O routine invokes the VAX/VMS macro DSBINT to block all 
interrupts. DSBINT raises IPL to IPL$ POWER and saves the previous 
IPL setting, that is, driver fork IPL, on the top of the stack. 
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9.3.9 Checking for Power Failure 


The start I/O routine examines the powerfail bits in the UCB” status 
word (UCBSV POWER in UCBSW STS) to determine whether a power failure 
has occurred since the start I/O routine gained control. If the bit 
is not set, the transfer can proceed. 


If the bit is set, a power failure may have occurred between the time 
that the start I/0 routine wrote the first device register and the 
time that the start I/O routine is ready to activate the device. Such 
a power failure could modify the already written device registers and 
cause unpredictable device behavior if the device were to be started. 


If the bit UCBSV_POWER is set, the start I/O routine branches to an 
error handler in the driver. The driver is responsible for clearing 
UCBSV_POWER before recovery or error procedures can be initiated. 
Many drivers clear this field and transfer to the beginning of the 
start I/O routine, which restarts processing of the I/O request. 


9.3.10 Activating the Device 


Tf no power failure has occurred, the start I/O routine copies’ the 
contents of the control mask (in this’ case, R3) into the device 
control/status register. When the device notices the new contents of 
the device register, the actual transfer begins. 


9.4 WAITING FOR AN INTERRUPT OR TIMEOUT 


Once the start I/O routine activates the device, the driver fork 
process cannot proceed until one of two external events occurs: 


e The device generates a hardware interrupt. 


e The device does not generate a hardware interrupt within an 
expected time limit; that is, a device timeout occurs. 


Still executing at IPLS POWER, the driver's start I/O routine asks 
VAX/VMS to suspend the driver fork process by invoking one of the 
following VAX/VMS macros: 


WFIKPCH -- Wait for an interrupt or timeout and keep the 
controller data channel 


WFIRLCH -- Wait for an interrupt or timeout and release the 
controller data channel 


Both of these macros invoke routines that return IPL to the previous 
tevel when they exit. These routines expect to find the return IPL on 
the stack. Original IPL is normally saved on the stack by the DSBINT 
macro, which the start I/O routine invokes before it checks for power 
failure, as described in Section 9.3.9. 


Drivers generally keep the controller data channel while waiting for 
the interrupt or timeout. Some I/O operations, however, do not need 
the controller after the operation is started, for example, a disk 
seek operation. 


Waiting for an interrupt or device timeout is the approach normally 
taken by drivers. 


CODING THE START I/O ROUTINE 


9.4.1 WFIKPCH and WFIRLCH Macro Formats. 


A start I/O routine invokes either the WFIKPCH or WFIRLCH macro to 
wait for device interrupt. 


Formats 
WFIKPCH excpt, [time] 
WFIRLCH excpt, [time] 
excpt 


The address of the timeout routine for this device. 


time 
The number of seconds to wait before signaling a device timeout. 
The number must be greater than or equal to 2. A minimum value 
of 2 is required because. the timeout mechanism 1s accurate only 
to within one second. If no number is specified, the macro uses 
.the value 65536 by default. 


9.4.2 Expansion of WFIKPCH Macro 


Because the WFIKPCH and WFIRLCH macros are similar, the description 
that follows analyzes the expansion of WFIKPCH only. 


If the driver specifies the time argument in the macro call, the macro 
pushes the value of the argument into the stack. If the time argument 
is not specified, the macro pushes the value 65536 onto the stack. 


The VAX/VMS timer routine uses the time value to calculate the length 
of time to wait before transferring control to a device timeout 
handler. 


WFIKPCH completes itS expansion with the following two lines of code: 


JSB G* IOCSWFIKPCH 
WORD EXCPT-. 


The execution of the JSB instruction pushes the address following the 
JSB onto the stack as the address to which the called routine would 
normally return with an RSB instruction. 


9.4.3 IOCSWFIKPCH Routine 


The VAX/VMS routine IOCSWFIKPCH invoked by the macro WFIKPCH performs 
the functions necessary for the driver fork process to wait for a 
device interrupt or timeout. IOCSWFIKPCH first adds 2 to the address 
on the top of the stack so that the top of the stack contains the 
address of the next instruction in the driver after the macro 
invocation. This address is where the driver processing actually 
resumes as a result of an interrupt service routine JSB instruction. 


IOCSWFIKPCH then saves the contents of R3, R4, and the driver’ return 
address from the top of the stack in the first part of the unit 
control block; that is, in the UCB fork block. The interrupt service 
routine must restore R5 to contain the address of the unit control 
block after an interrupt. The interrupt service routine normally 
obtains the address of the unit control block from the _ field 
IDBSL_OWNER of the interrupt data block. 


CODING THE START I/O ROUTINE 


The VAX/VMS routine that detects a device timeout calculates’ the 
address of the driver timeout routine by subtracting 2 from the saved 
PC in the UCB fork block and calling indirectly through the result, 
for example: 


MOVL UCBSL_FPC(R5) ,R2 Get saved PC 


CVTWL -(R2) ,-(SP) ; Get offset to timeout 
: handler 

ADDL (SP)+,R2 ; Add to relative driver 
; address to obtain relative 
; handler address 

JSB (R2) : Call timeout handler 


IOCSWFIKPCH sets bits in the unit control block (UCBSV INT and 
UCBSV_TIM in UCBSW STS) to indicate that interrupts and timeouts are 
expected from the device. IOCSWFIKPCH also writes the device timeout 
absolute time in the field UCBSL DUETIM. The absolute time is the 
number of seconds since the operating system was bootstrapped plus the 
number of seconds specified in the time argument to the macro. 


Finally, IOCSWFIKPCH reenables interrupts by lowering IPL to its 
previous level in the driver, that is, to driver fork level, and 
returns control to the caller of the driver. 


9.5 RESPONDING TO AN EXPECTED DEVICE INTERRUPT 


The only context saved for the driver is now in the unit control 
block. It contains the following information: 


e A description of the I/O request and the state of the device 
e The contents of R3 and R4 


e The implicit contents of R5, that is, the address of the UCB 
fork block 


e A driver return address 
e The implicit address of a device timeout routine 


By convention, R4 often contains the address of the control/status 
register; it permits the driver to examine device registers. When 
the driver fork process regains control after an interrupt processing, 
R5 contains the UCB address. It is the key to the I/O data base that 
is relevant to the current I/O operation. 


When a device interrupts, the driver interrupt service’ routine 
analyzes the interrupt, as detailed in Chapter 11 and summarized 
below: 


e Identifies the UCB address of the device that generated the 
interrupt 


e Obtains device or controller status from the device registers, 
-1f necessary, and stores the status in the unit control block 


e Restores the driver fork process registers from the UCB_ fork 
block, restores R5 with the UCB address, and reactivates the 
suspended driver at the PC stored in the UCB fork block 


If, instead of requesting an interrupt, the device times out, a 
VAX/VMS timer routine reactivates the suspended driver fork process at 
the address of the timeout routine. Section 12.2 discusses’ device 
timeout handling in detail. 
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CHAPTER 10 


CODING FOR UNIBUS DMA TRANSFERS 


A driver performing DMA transfers over the UNIBUS must take UNIBUS 
operation into consideration. The VAX/VMS operating system and the 
I/O data base handle most UNIBUS map register and data path’ resource 
management for the device drivers. You must choose the type of data 
path (either direct or buffered) appropriate to the device and ensure 
that UCB fields are written to describe the virtual memory locations 
to be read or written. Once these actions have been taken, the driver 
fork process calls VAX/VMS' routines to take care of the detailed 
operation of the UNIBUS adapter. 


The I/O data base contains an adapter control block (ADP) that 
describes the UNIBUS adapter. This block contains allocation bit maps 
for the UNIBUS adapter data paths and map registers. Each bit 
represents one data path or one map register. When the bit is clear, 
the data path or register is allocated to a device driver. 
The adapter control block also contains the virtual address of the 
UNIBUS adapter configuration register. All other adapter registers 
are located at fixed offsets from the configuration register. The 
VAX/VMS UNIBUS adapter-handling routines modify the UNIBUS adapter 
data path and map registers according to request from driver fork 
processes. 
In general, driver fork processes do not access the UNIBUS adapter 
control blocks. Instead, drivers call VAX/VMS routines that perform 
adapter-related services, such as the following: 

e Allocate a buffered data path 

e Allocate map registers 

e Load map registers 

e Deallocate map registers 

e Purge a buffered data path 

e Deallocate a buffered data path 
The system creates a driver fork process by calling the start I/0 
routine in a device driver. The fork process takes some or all the 
following steps to initiate an I/O transfer on a UNIBUS device: 

e Requests buffered data path 


e Requests map registers 


e Loads map registers 
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e Calculates starting UNIBUS address 
e Activates device 
e Waits for interrupt 


When a hardware interrupt indicates that the I/O transfer is complete, 
the driver fork process checks the success or failure of the transfer. 
The driver then concludes with the following steps: 


e Purges the buffered data path 
e Releases the data path 
e Releases the map registers 


All of the steps above involve the UNIBUS adapter. VAX/VMS, however, 
hides most of the UNIBUS interfacing from the driver. 


10.1 REQUESTING A BUFFERED DATA PATH 


The system provides two macros that a driver can invoke to request a 
buffered data path: 


e REQDPR, which suspends the driver to wait for a buffered data 
path if one is not available 


@e REQDATAPNW, which returns an error status if no buffered data 
path is available 


In addition, a driver can request the permanent allocation of a 
buffered data path, as described in Section 10.1.3. 


10.1.1 Requesting a Buffered Data Path (with Wait) 


A driver fork process requests a buffered data path by invoking’ the 
VAX/VMS macro REQDPR. REQDPR calls a VAX/VMS- routine named 
IOCSREQDATAP that locates the UNIBUS adapter control block. To do 
this, IOCSREQDATAP uses a series of pointers that begin in the current 
unit control block, as follows: | 


UCB —3 CRB —s ADP 


The ADP data path bit map indicates the buffered data paths that are 
available. IOCSREQDATAP allocates a data path to the driver by 
Storing the data path number in the channel request block and 
indicating in the adapter control block (ADP) that the data path is in 
use. Then, control returns to the driver fork process. Appendix A 
describes the adapter control block. 


If no data path is available, IOCSREQDATAP saves driver context (R3, 
R4, and PC) in the UCB fork block and inserts the address of the fork 
block, which is also the address of the unit control block and _ the 
content of R5, in the ADP data path wait queue. The driver fork block 
remains in the queue until both of the following conditions are met: 


e A data path is available 


e The driver fork block is the next entry in the data path wait 
queue 
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Then, the VAX/VMS routine IOCSRELDATAP allocates the data path to’ the 
suspended driver and reactivates the driver fork process. 


10.1.2 Requesting a Buffered Data Path (No Wait) 


Instead of invoking REQDPR, the driver fork process can call the 
subroutine IOCSREQDATAPNW by invoking the macro REQDATAPNW. 


This routine immediately returns control to the driver fork process if 
no data path is available. The low-order bit of RO is clear, 
indicating that the request for allocation was unsuccessful. 


If the data path is available, IOCSREQDATAPNW allocates the data path 
and returnS a normal status code (SSS NORMAL) to the driver fork 
process in RO. 


10.1.3 Requesting A Permanent Buffered Data Path 


A device driver also can permanently allocate a buffered data path 
with code in a device unit initialization routine. The following 
steps permanently allocate a buffered data path: 


e Invoke the REQDPRNW macro or the REQDPR macro to allocate a 
data path 


e Set the path lock bit in the data path number field of the 
channel request block (VECSV_PATHLOCK in 
CRBSL_INTD+VECSB_DATAPATH) 


When the driver loading procedure loads or reloads the driver, the 
procedure calls the unit initialization routine for each device unit 
associated with the driver. At that time, the unit initialization 
routine permanently allocates a buffered data path for each device 
unit if the code described above has been included. 


10.1.4 Requesting the Direct Data Path 


Because the UNIBUS adapter arbitrates among devices that wish to use 
the direct data path and because the CRB is initialized to 0 
(0 = direct data path), drivers are not required to invoke the REQDPR 
macro to request the direct data path. 


When a word-aligned UNIBUS device uses the direct data path, the 
driver must ensure that the specified buffer is on a word boundary, 
Since byte offset is not implemented on the direct data path. 


10.1.5 Mixed Direct and Buffered Data Path Transfers 


A device driver can use the buffered data path for certain operations, 
then use the direct data path for other operations. To accomplish 
this task, the driver should allocate a buffered data path (for 
buffered I/0. When the operation completes, the driver should then 
purge and release the data path. The release automatically resets the 
data path number to zero, which signifies a direct data path. 
However, the driver should take care not to release the direct data 
path, although it can purge the path if desired. (A purge of the 
direct data path is a NOP and always yields success.) 
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10.2 REQUESTING UBA MAP REGISTERS 


The operating system allows a driver to allocate map registers as 
needed or to allocate them permanently. 


10.2.1 Allocation of Map Registers 


A driver fork process requests a set of UNIBUS adapter map registers 
by invoking the VAX/VMS macro REQMPR. This macro calls the routine 
ITOCSREQMAPREG. IOCSREQMAPREG calculates the number of map registers 
needed for a transfer. The calculation is based on the transfer byte 
count field and the byte offset field of the device's unit control 
block (UCBSW_BCNT and UCBSW BOFF). 


The procedure for allocating map registers is similar to that used to 
allocate a buffered data path. First, IOCSREQMAPREG locates the 
adapter control block from a series of pointers that begin with the 
current unit control block, as follows: 


UCB —. CRB —=s ADP 


Then, the routine examines the map register allocation bit map _ to 
locate the required number of contiguous map registers. If the 
registers are not currently available, IOCSREQMAPREG saves the driver 
context (R3, R4, and PC) in the UCB fork block and inserts the fork 
block address (same as UCB address and the contents of R5) in the map 
register wait queue. 


When the map registers are available, IOCSREQMAPREG allocates them by 
clearing the appropriate bits in the map register bit map of the ADP. 
IOCSREQMAPREG then writes the number of the starting map register and 
the number of map registers allocated into the channel request block 
and returns control to the driver fork process. 


10.2.2 Permanent Allocation of Map Registers 


A device driver also can permanently allocate a set of UNIBUS adapter 
map registers with code in a unit or controller initialization 
routine. You must enSure that the number of map registers permanently 
allocated is sufficient for the longest possible transfer. The 
following steps permanently allocate a set of map registers: 


e Load the number of map registers required into R3. 


e Call the VAX/VMS routine I OCSALOUBAMAPN with a JSB 
instruction: 


JSB G* IOCSALOUBAMAPN 
If IOCSALOUBAMAPN successfully allocates the map registers, it 
stores the number of map registers allocated and the starting 
map register's number in the channel request’ block at 
CRBSL_INTD+VECSB_NUMREG and CRBSL_INTD+VECSW_MAPREG, 
respectively, and returns with the low-order bit set in RO. 
Otherwise, it returns with the low-order bit of RO clear. 


e Set the map lock bit in the channel request block 
(VECSC_MAPLOCK in CRBSL_INTD+VECSW_MAPREG). 
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When the driver loading procedure loads or reloads the driver, the 
procedure calls the unit or controller initialization routine for each 
device unit or controller associated with the driver. At that time, 
the initialization routines can permanently allocate map registers. 


10.3 LOADING THE UBA MAP REGISTERS 


Once a driver fork process has assigned a data path and allocated a 
set of map registers, it can request VAX/VMS to load the map registers 
with physical page frame numbers by invoking the VAX/VMS-~ macro 
LOADUBA. LOADUBA calls a VAX/VMS routine IOCSLOADUBAMAP that loads 
each allocated map register with five data items: 


e A bit setting to indicate whether the map register is valid. 


e Abit setting to indicate whether the transfer is to start on 
the odd or even byte within a word; this bit is set if the 
low-order bit of UCBSW BOFF is a 1. 


e The number of the data path to use for the transfer. 
e The page frame number of a page in memory. 


e A bit setting to indicate that the transfer operates in 
longword-aligned random access’ mode; This bit is set when 
VECSV_LWAE is specified in VECSB DATAPATH. 


IOCSLOADUBAMAP loads the page frame number of the first page of the 
transfer into the first allocated map register, the page frame number 
of the second page of the transfer into the second map register, and 
So forth. 


IOCSLOADUBAMAP sets the valid bit in every allocated map register 
except the last. It clears the valid bit in the final map register to 
stop a prefetch from an invalid page frame number. 


To calculate the page frame number used in the I/0 transfer, 
IOCSLOADUBAMAP uses’ three fields that VAX/VMS has written into the 
unit control block: 


e UCBSW BOFF -- byte offset in the first page of the transfer 

e UCBSW BCNT -- number of bytes to transfer 

e UCBSL SVAPTE -- virtual address of the page table entry that 
contains the page frame number of the first page of the 
transfer 


IOCSLOADUBAMAP determines the data path number, the number of the 
first map register, the address of the first map register, and the 
number of map registers from the channel request block and the UNIBUS 
adapter control block, as follows: 

UCB —»sCRB —=sdata path number 

UCB —™ CRB — number of first map register 


UCB —CRB —-ADP ~— virtual address of first map register 


UCB —»CRB —™ number of map registers 
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Drivers that handle byte-addressable UNIBUS devices call the routine 
IOCSLOADUBAMAPA. This routine performs the same function as 
IOCSLOADUBAMAP, with one exception. When IOCSLOADUBAMAPA loads’ map 
registers, it clears the byte offset bit even if the transfer begins 
on an odd-byte address. 


When IOCSLOADUBAMAP has loaded all the map registers and marked _ the 
last map register invalid, it returns control to the driver fork 
process. 


10.4 COMPUTING THE STARTING ADDRESS OF A TRANSFER 


The driver fork process must calculate the starting address of a 
UNIBUS transfer and load this address into the appropriate device 
register. The driver takes the following steps. to make the 
calculation: 


e Writes the byte offset in page field of the UCB (UCBSW_BOFF) 
into bits 0 through 8 of a register 


e Gets the number of the starting map register for the transfer 
from the channel request block; the number is a 9-bit value 


e Writes bits 0 through 6 of the map register number into bits 9 
through 15 of the register containing the byte offset field 


e Writes bits 0 through 15 of the register into the buffer 
address register for the device 


e Writes bits 7 and 8 of the map register number into’ the 
extended memory bits of the appropriate device register 
(usually the control/status register) 


10.5 ACTIVATING THE DEVICE 


Because a driver fork process can address device registers as _ though 
they were any other virtual address, the loading of the UNIBUS buffer 
address register and control/status register both are simple 
procedures. The driver locates the CSR address of the device in the 
interrupt data block, as follows: 


UCB —=» CRB —* IDB — CSR address 


The CSR address is the virtual address of a device register. All 
other device registers are located at constant offsets from the CSR 
address. If, for example, the control/status register is the first 
device register and the device word count is the third device 
register, the device driver can load the word count register with the 
following sequence of instructions: 


e Move the CSR address into R4 


@e Move the number of words to transfer with a MOVW instruction 
that addresses 4(R4) 
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10.6 COMPLETION OF A DMA TRANSFER 


After a driver fork process activates a DMA UNIBUS device, the driver 
waits for a device interrupt by invoking a VAX/VMS macro that suspends 
the driver. When the UNIBUS device requests a hardware interrupt, a 
VAX/VMS interrupt dispatcher gains control. The dispatcher saves RO 
through R5 and transfers control to code in the channel request block. 


The CRB code calls a driver interrupt service routine. If the service 
routine can match the interrupt with a suspended driver fork process, 
the interrupt Service routine reactivates the driver fork process at 
the point that execution was suspended. The driver almost immediately 
invokes the VAX/VMS macro IOFORK. 


IOFORK calls the VAX/VMS routine EXESIOFORK. EXESIOFORK saves’ the 
driver context (R3, R4, and PC) in the UCB fork block and inserts the 
address of the fork block (R5) in the device's fork queue. EXESIOFORK 
then returns control to the driver's interrupt service routine, which 
dismisses the interrupt. 


When the fork dispatcher reactivates the driver fork process, the 
driver performs any necessary UNIBUS adapter clean-up operations, such 
as data path purging and deallocation of UNIBUS adapter resources used 
in the DMA transfer. | 


10.6.1 Purging the Data Path 
Driver fork processes that use buffered data paths must purge the data 
path after the DMA transfer is complete. The driver invokes the macro 
PURDPR, which in turn calls the VAX/VMS routine IOCSPURGDATAP. This 
routine takes the following steps to purge the data path: 

e Saves the contents of R4 on the stack 


e Locates the channel request block as follows: 


R5 — = UCB —=» CRB 


e Obtains the starting address of UNIBUS adapter register space 
and stores it in R2 


e Extracts the number of the data path to be purged from the 
channel request block and loads it into Rl 


e Stores the address of the data path in R4 


e Purges the data path (performed by the UNIBUS adapter). The 
routine then modifies RO through R2 to contain the following 
information: 


RO Success/failure status. If the purge completes 
without error, the routine sets SS$ NORMAL in this 
register. If a data path error does occur, RO is 
clear and the hardware is reset. 


Rl Contents of the data path register 

R2 Address of the first UNIBUS adapter map register 

The address of the channel request block remains in R3. This 
address, along with the information in Rl and R2, is used as 


input to the error-logging routine in the event of a data 
path error. 
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e Restores the information stored on the stack to R4 and 
returns to PURDPR. 


If a data path error occurs during a data path purge, the driver 
Should retry the entire DMA transfer. 


10.6.2 Releasing a Buffered Data Path 


A driver fork process releases a buffered data path by invoking’ the 
VAX/VMS macro RELDPR. RELDPR calls a VAX/VMS routine IOCSRELDATAP 
that determines which data path was assigned to the driver’ fork 
process and releases the data path to a waiting driver. The driver 
must be executing at fork IPL. 


The data path number is stored in the channel request block. 
IOCSRELDATAP locates it as follows: 


UCB —= CRB — data path number 


If the data path is permanently assigned to a device, IOCSRELDATAP 
does not release the data path. Otherwise, the data path number in 
the channel request block (CRBSL INTD + VECSB DATAP) is zeroed. The 
IOCSRELDATAP routine attempts to dequeue a waiting driver fork process 
from the data path wait queue stored in the adapter control block as 
follows: 


UCB — CRB —=™ ADP —™ data path wait queue 


If another driver is waiting for a buffered data path, IOCSRELDATAP 
grants that driver fork process the data path, restores its driver 
context from its UCB fork block, and transfers control to the saved 
driver PC. When IOCSRELDATAP can allocate no more data paths, the 
routine returns to the driver that released the data path. This 
diversion of driver processing iS transparent to the driver fork 
process. 


If the data path wait queue is empty, IOCSRELDATAP marks the data path 
as available in the I/O data base and returns control to the driver. 


10.7 RELEASING UBA MAP REGISTERS 


A driver fork process releases a set of UNIBUS adapter map registers 
by invoking the VAX/VMS macro RELMPR. RELMPR calls the VAX/VMS 
routine IOCSRELMAPREG that releases map registers in a manner’ similar 
to that in which data paths are released. The channel request block 
records the map register numbers assigned to the device. The number 
of the first map register and the number of map registers are located 
as follows. The driver must be executing at fork IPL. 


UCB —= CRB —™ number of the first map register 

UCB —= CRB —* number of map registers allocated 
IOCSRELMAPREG releases the map registers by setting the corresponding 
bits in the map register allocation bit map, which it locates as 


follows: 


UCB —» CRB — = ADP —» map register bit map 
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Then, IOCSRELMAPREG attempts to dequeue a driver fork process from the 
map register wait queue. If a suspended driver is’ found, 
IOCSRELMAPREG takes the following steps: 

e Dequeues the fork block and restores driver context 


e Fills the map register request, if possible 


e Reactivates the driver fork process at the instruction 
following the driver's request for map registers 


e Returns to the driver fork process 
If the map register wait queue is empty or if IOCSRELMAPREG still does 
not have enough contiguous map registers for any of the waiting fork 


processes, it returns control to the driver fork process that released 
the map registers. 
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CODING INTERRUPT SERVICE ROUTINES 


The driver prologue table of most device drivers contains, in the 
reinitialization section established using the DPT STORE macro, the 
address of one or more interrupt service routines. Each interrupt 
service routine corresponds to an interrupt vector on the UNIBUS. You 
specify the UNIBUS vector address in the CONNECT command to the SYSGEN 
utility, as described in Chapter 14. 


Most interrupt service routines in device drivers perform the 
following functions: 


e Locate the device's unit control block 
e Determine whether the interrupt was solicited 


e Reject or process unsolicited interrupts 
e Activate the suspended driver to process solicited interrupts 


Figure 11-1 illustrates the general flow of interrupt handling. The 
remaining sections of this chapter describe the handling of solicited 
and unsolicited interrupts in further detail. 


11.1 DELIVERING A DEVICE INTERRUPT TO A DRIVER 


When a UNIBUS device requests a hardware interrupt, the device puts a 
vector address on UNIBUS lines and the vector address is loaded into a 
UNIBUS adapter register. When the processor executes at an interrupt 


priority level below the hardware interrupt level of the device, the 
following sequence occurs: 


e The processor saves the PC and PSL of the currently executing 


code on the interrupt stack and transfers control to the 
VAX/VMS UNIBUS adapter interrupt service routine. 


e The UNIBUS adapter service routine then saves RO through R5 on 
the stack and, using a JMP instruction, transfers control to 
executable code in the channel request block that the driver 
loading procedure has associated with the interrupting vector. 
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The CRB interrupt dispatching field (CRBSL_INTD+2) contains’ the 
following executable instruction: 


JSB @#address-of—-driver-isr 


The driver loading procedure writes these instructions into’ each 
channel request block as_ the procedure creates the control blocks. 
The driver loading procedure obtains the address of the interrupt 
service routine from the reinitialization portion of the driver 
prologue table. If the device has two interrupt vectors, for example, 
and its driver specifies two interrupt service routine addresses in 
the DPT reinitialization section, the driver loading procedure creates 
a channel request block with two interrupt dispatching fields. 


Immediately following the JSB instruction in the channel request block 
is the address of the interrupt data block associated with the CRB. 
When the JSB instruction executes, a pointer to the address of the 


interrupt data block is pushed onto the top of the stack as though it 
were a return address. The driver interrupt service routine can _ use 


this IDB address aS a pointer into the I/O data base. Figure 11-2 
iilustrates the portion of a channel request block that contains’ the 
interrupt service routine address. 


JSB @# | 
INTERRUPT SERVICE ROUTINE ADDRESS 


INTERRUPT DATA BLOCK ADDRESS 


CHANNEL REQUEST BLOCK: 






Figure 11-2 Channel Request Block 
Containing an Interrupt Service Routine Address 


11.2 INTERRUPT CONTEXT 


When the UNIBUS adapter interrupt service routine calls a driver 
interrupt service routine, execution context is as follows: 


e RO through R5 are saved on the stack. 


e System address space is mapped. The service routine can gain 
access to appropriate control blocks in the I/O data base. 


e IPL is at hardware device interrupt level. 
e The processor is running in kernel mode. 


e The processor is running on the interrupt stack. 
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The UNIBUS adapter interrupt service routine does not load any 
registers for the driver interrupt service routine; however, the 
stack contains the following information: 


Stack Location Content 

0 (SP) Pointer’ to the address of the 
interrupt data block 

4(SP) through 24(SP) Saved RO through R5 

28 (SP) PC at the time of the interrupt 

32 (SP) PSL at the time of the interrupt 


11.3 SERVICING A SOLICITED INTERRUPT 


When a driver fork process activates a device and expects to service a 
device interrupt as a result, the driver suspends fork processing and 
waits for an interrupt to occur. The suspended driver is represented 
only by the contents of the device'S unit control block, which 
contains a description of the I/O request and the driver fork process. 
When the driver regains control from the interrupt service routine, 
only R3, R4, R5, and the PC address are restored to their previous 
State by the interrupt service routine. 


In the sequence below, a driver interrupt service routine returns 
control to the waiting driver: 


e First the interrupt service routine obtains the address of the 
device's unit control block from the interrupt data block, as 
Follows: 


O(SP) —*™ CRB —*IDBSL OWNER — UCB for the device 


e The service routine then tests the software interrupt expected 
bit in the UCB status word (UCBSV INT in UCBSW STS). If the 
bit is set, the driver is waiting for an interrupt from this 
device. | 


e The interrupt service routine restores R5 of the driver fork 
process with the address of the UCB fork block. It restores 
R3 and R4 of the driver process uSing two fields from the UCB 
fork block, UCBSL FR3 and UCBSL FR4, respectively. 


e Finally the interrupt service routine transfers control to the 


driver PC address saved in the UCB fork block at UCBSL_FPC by 
issuing a JSB instruction. 


The restored driver can execute a few instructions in the context of 
the interrupt, such as copying device status information from the 
device registers into the device's UCB. Before completing the I/O 
operation, however, the driver routine creates a fork process to lower 
its execution IPL to driver fork level instead of continuing execution 
at hardware device interrupt IPL. The driver routine creates a fork 
process by invoking the VAX/VMS macro IOFORK, as described in Section 
Lele ls 
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IOFORK calls the VAX/VMS routine EXESIOFORK. EXESIOFORK inserts’ the 
UCB fork block describing the driver process in the appropriate fork 
queue and returns control to the driver interrupt service routine. 
The interrupt service routine then performs the following steps: 


e Removes the IDB pointer from the stack 
e Restores RO through R5 


e Dismisses the interrupt with an REI instruction 


11.4 SERVICING AN UNSOLICITED INTERRUPT 


Devices request interrupts to indicate to a driver interrupt service 
routine that the device has changed status. If a driver fork process 
Starts an I/O operation on a device, the driver expects to receive = an 
interrupt from the device when the I/O operation completes or an error 
occurs, 


Other changes of device status occur when the device has not been 
activated by a device driver. The device reports these changes by 
requesting unsolicited interrupts. For example, when a user types. on 
a terminal that is not attached to a process, the terminal requests an 
interrupt that is fielded by the terminal driver. As a result of the 
interrupt, the terminal driver causes the login procedure to be 
invoked for the user at the terminal. 


Another example of an unsolicited interrupt is one that the unit 
requests when an operator changes the volume on a disk drive. The 
disk driver services the interrupt by altering volume and unit status 
bits in the disk device's unit control block. 


Devices request unSolicited interrupts because some external event has 
changed the status of the device. A device driver can handle these 


interrupts in two ways: 
e Ignore the interrupt as spurious 


e Examine the device registers and take action according to 
their indications of changed status, and then poll for any 
other changes in device status 


The driver interrupt service routine decides whether an interrupt is 
solicited or not by examining the software interrupt expected bit in 
the UCB status word (UCBSV INT in UCBSW STS). If the interrupt is 
unsolicited, the driver can reject the interrupt with the following 
code sequence: 


e Remove the IDB pointer from the stack 
@e Restore RO through R5 
e Dismiss the interrupt with an REI instruction 


Rather than rejecting the interrupt, the driver may wish to handle it. 
For example, the driver can send a message to the operator or the job 
controller mailbox when an unsSolicited interrupt occurs. 


Drivers Should avoid creating a fork process to handle unsolicited 
interrupts from busy devices. The unit control block of a busy device 
may contain the active fork block of a previously created driver fork 
process. If an unsolicited interrupt service routine should create a 
fork process to handle its request, it may destroy the driver’ fork 
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context currently stored there. Drivers should always handle this 
type of unsolicited interrupt at hardware device IPL. 


11.4.1 Examples Of Unsolicited Input Handling 


A card reader device requests an unsolicited interrupt if any user 
turns the reader online. Once the card reader driver interrupt 
service routine determines that the interrupt is unsolicited, the 
routine analyzes the interrupt, as in the following example: 


e It obtains the address of the control/status register using 
the interrupt data block pointed to by the address on the top 
of the interrupt stack, as follows: 


0(SP) —m CRB — =» IDB —* CSR address 


e It confirms that the reader has just been placed online by 
examining the online bit in the control/status register. 


e It examines the reference count field of the device's unit 
control block (UCBSW REFC) to determine whether a process has 
assigned or allocated the device. If the count is nonzero, 
the interrupt service routine removes the IDB pointer from the 
stack, restores RO through R5, and dismisses the interrupt 
with an REI instruction. 


e If the reference count is zero, the interrupt service routine 
clears the status bit in the control/status register. 


e It confirms that the job controller has not received a message 


about the device's being online by testing the job-attached 
bit in the UCB status word (UCBSV_JOB in UCBSW STS). 


e If the job-attached bit is not set, it sets the job-attached 
bit and creates a fork process that is to send a message to 
the job controller. The VAX/VMS routine that creates the fork 
process returns to the driver's interrupt service routine. 


e Finally, the interrupt service routine removes the IDB pointer 
from the stack, restores RO through R5, and dismisses the 
interrupt with an REI instruction. 


Another example of unsolicited interrupt processing occurs in a device 
driver for a multiunit controller. When the operator removes a disk 
volume, the disk drive requests an interrupt. The driver interrupt 
service routine must determine what drive unit requested the 
interrupt, obtain drive status from the drive's control/status 
register, and then decide whether the interrupt was solicited. If the 
interrupt is unsolicited, the driver service routine calls its 
unsolicited interrupt routine. The routine checks the status of the 
volume, as described in the following steps: 


e It sets a bit in the unit control block to indicate that the 
unit is online (UCBSV_ONLINE in UCBSW STS). 


® If the UCB volume valid bit is set (UCBSV_VALID in UCBSW STS), 
the routine tests the volume valid status bit in a device 


register to determine whether the volume status has’~ changed. 
If the volume is no longer valid, the routine clears the UCB 
volume valid bit. 


e Finally, the routine returns to the normal driver interrupt 
service routine. 
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The driver interrupt service routine then polls the other device units 
on the controller to determine whether any other units requested 


interrupts while the first interrupt was being processed. When no 
unit requires interrupt servicing, the routine removes the IDB pointer 


from the stack, restores registers RO through R5, and dismisses’ the 
interrupt with an REI instruction. 


Lia 


CHAPTER 12 


COMPLETING THE I/0 REQUEST 


Once a driver has activated the device and invoked the wait for 
interrupt macro, the driver remains suspended until one of the 
following events occurs: : 


e The device requests an interrupt 
e The device times out 


If the device requests an interrupt, the driver interrupt service 
routine handles the interrupt and then reactivates the driver at the 
instruction following the wait for interrupt macro. The reactivated 
driver performs device-dependent I/0 postprocessing. 


If the device does not request an interrupt within the designated time 
interval, the system transfers control to the driver's timeout 
handler. The address of the timeout handler is specified as an 
argument to the wait for interrupt macro invocation. 


12.1 I/O POSTPROCESSING 


Once the driver interrupt service routine has handled an interrupt, it 
transfers control to the driver by issuing a JSB instruction. At this 
point, the driver is executing in interrupt context. If the driver 
were to continue executing in interrupt context, it would lock out 
most other processing on the processor including the handling of 
hardware interrupts. To restore the driver to the context of a driver 
fork process, the driver invokes the VAX/VMS macro IOFORK. Once the 
fork process has been created and dispatched for execution, it 
executes the driver code that completes the processing of the I/0 
request. 


12.1.1 EXESIOFORK 


IOFORK is a macro that generates a call to the VAX/VMS”~ routine 
EXESIOFORK. EXESIOFORK converts’ the driver context from that of an 
interrupt service routine to the context of a driver fork process in 
the following steps: 


e It disables software timeouts by clearing the timeout’ enable 
bit in the UCB status word (UCBSV_TIM in UCBSW_STS). 


e It saves R3 and R4 of the current driver context in the UCB 
fork block (UCBSL_FR3 and UCBSL FR4). 
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e EXESIOFORK then saves the current driver PC in the UCB- fork 
block (UCBSL FPC). The driver PC is the first longword on the 
Stack upon entry to EXESIOFORK as ae result of the JSB 
instruction. 


e It obtains the fork IPL of the device from the UCB 
(UCBSB FIPL). 


e It inserts the address of the UCB fork block (R5) into’ the 
fork queue correSponding to the driver fork IPL. 


e Finally, if the fork block is the first entry in the fork 
queue, EXESIOFORK requests a software interrupt at driver fork 
IPL. 


The steps listed above move the critical driver fork process’ context 
into the UCB fork block; that is, they save R3 through R5 and the 
driver PC address. The driver fork process resumes’ processing when 
the VAX/VMS fork dispatcher dequeues the UCB fork block from the fork 
queue and reactivates the driver at driver fork IPL. 


12.1.2 Completing an I/O Request 


When VAX/VMS reactivates a driver fork process by dequeuing the fork 
block, the driver resumes’ processing of the I/O operation. If the 
device has completed the I/O operation without errors, the driver fork 
process for a DMA device proceeds as follows: 


e Purges the buffered data path 

e Releases the buffered data path 
e Releases map registers 

e Releases the controller 


e Saves the status code, transfer count, and device-dependent 
Status that is to be returned to the user process in an I/0 
Status block 


e Returns control to the operating system 


Chapter 10 discusses the first three steps listed above because _ they 
relate to UNIBUS DMA transfers. The sections that follow describe the 
remaining three steps. 


12.1.2.1 Releasing the Controller - To release the controller 
channel, the driver code invokes the VAX/VMS macro RELCHAN. RELCHAN 
calls the VAX/VMS routine IOCSRELCHAN. If another driver is waiting 
for the controller channel, IOCSRELCHAN grants that driver fork 
process the channel, restores its driver fork context from its UCB 
fork block, and transfers control to the saved PC. When no more 
drivers are awaiting the channel, IOCSRELCHAN returns control to the 
driver fork process that released the channel. (The driver must be 
running at fork IPL.) 
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12.1.2.2 Saving Status, Count, and Device-Dependent Status - To save 
the Status code, transfer count, and device-dependent status, the 
driver performs the following steps: 


e It loads a success status code (SSS NORMAL) into bits 0 
through 15 of RO. 


e If the I/O operation performed by the device iS a transfer 
function, the driver loads the number of bytes transferred 
into the high-order 16 bits of RO, that is, into bits 16 
through 3l. 


e The driver then loads device-dependent status information, if 
any, into Rl. RO and Rl are the status values that VAX/VMS 
returns to the user process in the I/O status block specified 
in the original Queue I/O Request system service. If the user 
specifies no I/O status block, VAX/VMS makes no use of RO and 
Rl. 


12.1.2.3 Returning to the Operating System - Finally, the driver 
returns to the system by invoking the VAX/VMS macro REQCOM to complete 
the I/O request. REQCOM calls the VAX/VMS' routine IOCSREQCOM. 
IOCSREQCOM locates the address of the I/O request packet corresponding 
to the I/O operation in the device's UCB (UCBSL IRP). It then writes 
the two longwords of completion status contained in RO and Rl into the 
media field of the I/O request packet (IRPSL MEDIA and IRPSL MEDIA+4). 


IOCSREQCOM then inserts the I/0 request packet in the I/O 
postprocessing queue. If the packet is the only entry in the 
postprocessing queue, IOCSREQCOM requests a software interrupt at 
IPLS$_ IOPOST So the postprocessing begins when IPL drops’ below 
IPL$ IOPOST. 
If the error-logging bit is set in the device's unit control block 
(UCBSV_ERLOGIP in UCBSW_STS), IOCSREQCOM obtains the address of the 
error message buffer from the unit control block (UCBSL EMB). It then 
writes the following information into the error buffer: 

e Final device status (UCBSW DEVSTS) 

e Final error count (UCBSB_ERTCNT) 

e Two longwords of completion status (RO and Rl) 
To release the error message buffer, IOCSREQCOM calls ERLSRELEASEMB. 


If any I/O request packets are awaiting driver processing, IOCSREQCOM 
performs the following steps: 


e Dequeues a packet 

e Creates a new driver fork process 

e Activates the driver at the driver's start I/O routine 
Otherwise, IOCSREQCOM clears the unit busy bit in the device's UCB 
status word (UCBSV_BSY in UCBSW STS) and transfers control to 
IOCSRELCHAN to release the controller channel in case the driver 


failed to do so. 


The remaining steps in processing the I/O request are performed by 
VAX/VMS I/0 postprocessing. 
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12.2 TIMEOUT HANDLERS 


VAX/VMS transfers control to the driver's timeout handler if a device 
unit does not request an interrupt within the time limit specified in 
the wait for interrupt macro. The VAX/VMS timer routine scans device 
unit control blocks once every second to determine whether a device 
has timed out. 


When the timer routine locates a device that has timed out, the 
routine calls the device's timeout handler by performing the following 
steps: 
e It disables expected interrupt and timeout on the device by 
clearing bits in the device's UCB status field (UCBSV INT and 
UCBSV_TIM in UCBSW STS). 7 


e It sets the device timeout bit in the UCB status field 
(UCBSV_TIMOUT in UCBS$W_ STS). 


e It sets IPL to hardware device interrupt IPL (UCBSB DIPL). 


e It restores the saved R3 and R4 of the driver fork process 
from the UCB fork block (UCBSL_ _FR3 and UCBSL FR4). 


e It restores R5 (address of the UCB fork block). 


e It computes the address of the driver's device timeout routine 
From the saved PC in the UCB fork block (UCBSL FPC). 


e It calls the device timeout routine with a JSB instruction. 


During power failure recovery, VAX/VMS forces a device timeout by 
altering the timeout field (UCBSL DUETIM) of a unit control block if 
the device UCB records that the unit is waiting for an interrupt or 
timeout (UCBSV INT and UCBSV TIM set in UCBSW STS). The timeout 
handler can perceive that a power failure recovery is occurring by 
examining the power bit (UCBSV_POWER in UCBSW_STS) in the unit control 
block. 


A timeout handler usually performs either of three functions: 
e Retries the I/O operation unless a retry count is exhausted 
e Aborts the I/O request 


e Sends a message to an operator mailbox and resumes waiting for 
a subsequent interrupt or timeout 


12.2.1 Retrying the I/O Operation 


some devices may retry an I/O operation after a timeout. For example, 
a disk driver might take the following steps after a transfer timeout: 


e Set IPL to driver fork level. Note that this IPL must not 
drop below IPLS TIMER, the level at which interval timer 
interrupts occur. 


e Release map registers, data path, and controller data channel. 
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e If a power failure occurred, load the I/O request packet 
address into R3 and reload the following I/O request packet 
fields into the corresponding UCB fields and branch to the 
Start I/O routine: 


UCBSW_BCNT 
UCBSW_BOFF 
UCBSL SVAPTE 
The above steps result in a total retry of the transfer. 
e If no power failure haS occurred and the device driver 
Supports error-logging, call ERLSDEVICTMO to log the device 
timeout 


e If the retry count is not exhausted, decrease the count, clear 
the UCB timeout bit in UCBSW_STS, and retry the operation. 


e If the retry count is exhausted, set the error code, perform a 
normal abort I/0 clean-up operation, and invoke REQCOM. 


12.2.2 Aborting the I/O Request 

A driver's timeout routine aborts the I/O request when it exhausts its 
retry count, or when it determines, upon timeout, that a cancel I/O 
was requested (UCBSV_CANCEL is set in UCBS$W_STS). 


A device driver timeout handler can abort the I/O request using’ the 
following sequence of steps: 


e If appropriate to the device and controller, the handler 
Clears the device control/status register. 


e The handler then invokes the following VAX/VMS macro to lower 
IPL to device fork level: 


SETIPL UCBSB_FIPL(R5) 
The resulting IPL must not drop below the interval timer IPL. 


e The handler releases UNIBUS adapter resources and the 
controller data channel, if necessary. 


e It loads an error status code into the low word of RO. 


e It clears bits 16 through 31 in RO to indicate that no data 
was transferred. 


e It invokes the VAX/VMS macro REQCOM, described in Section 
12.1.2.3, to complete the I/O request processing. 


Since the device can interrupt driver timeout processing at fork IPL, 
the interrupt service routine Should check the interrupt expected bit 
(UCBSV_INT) before handling the interrupt. The operating system 
clears this bit before it calls the driver's timeout routine. 
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Sending a Message to the Operator 


The following sequence describes a timeout handler that sends a 


message 


to the operator mailbox and then goes back into a wait for 


interrupt or timeout state: 


It invokes the following VAX/VMS macro to lower IPL to driver 
fork level: 


SETIPL UCBSB_ FIPL(R5) 


It checks the cancel I/O bit in the UCB) status word 
(UCBSV_CANCEL in UCBSW_ STS). 


If UCBSV_ CANCEL is set, the timeout handler performs’ the 
following: 


-- Loads the abort status code (SSS ABORT) into the low word 
of RO 


-- Writes other status information into RO and/or Rl 


-- Invokes the VAX/VMS macro REQCOM to complete the I/0 
request processing 


If UCBSV_CANCEL is not set, the timeout handler performs’ the 
following: 


-~- Saves R3 and R4 on the stack 


-- Loads an OPCOM message code, such as MSG$ DEVOFFLIN, into 
R4 


-- Loads the address of the operator mailbox (SYSSGL OPRMBX) 
into R3 


-- Calls a VAX/VMS routine to place the message in the 
operator mailbox, as follows: 


JSB G*EXESSNDEVMSG 
~- Restores R3 and R4 
The timeout handler then invokes the VAX/VMS macro DSBINT to 
raise IPL to IPLS$ POWER, thereby locking out all interrupts 


from software and hardware. 


Finally, the timeout handler invokes the VAX/VMS macro WFIKPCH 
to wait for another interrupt or timeout. 
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CODING INITIALIZATION, CANCEL I/0, AND ERROR-LOGGING ROUTINES 


Drivers normally contain initialization, cancel I/O, and error-logging 
routines. The driver prologue table specifies the address of 
initialization routines. The driver dispatch table contains’ the 
addresses of the cancel I/O and error-logging routines. Whether these 
routines are required depends on the type of device. 


13.1 INITIALIZATION ROUTINES 


Most device controllers and device units require initialization under 
the following circumstances: 


e When the driver loading procedure loads a device driver for 
the controller and device units 


e During recovery from a power failure 
Initialization routines ready controllers and device units for 
operation. Depending on the device characteristics, initialization 
routines perform any of the actions listed below: 

e Enable controller interrupts 


e Clear error status bits in device registers 


e Initiate a device operation such as clearing a drive or 
acknowledging a pack 


e Store values in UCB fields that cannot be addressed with a 
DPT STORE macro; that is, fields more than 256 bytes from the 
Start of the unit control block 


e Permanently allocate UNIBUS adapter reSources, as described in 
Chapter 10 


e Set the online bit (UCBSV_ONLINE in UCBSW_STS) in the unit 
control block 


e Fill in IDBSL OWNER for single-unit devices such as a _ line 
printer 
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13.1.1 Initialization During Driver Loading 


The driver loading procedurel loads and reloads drivers in the 
following steps: 


e It loads a driver into nonpaged system memory. If the 
procedure is loading the driver for the first time since the 
system was bootstrapped, it creates unit control blocks, a 
channel request block, an interrupt data block, and a device 
data block. 


e According to the DPT STORE macro invocations in the driver, 
the loading procedure writes the addresses of initialization 
routines in the channel request block of the controller’ and 
initializes other fields in other control blocks. 


e It raises IPL to IPL$ POWER to block all interrupts. 


e It calls the controller initialization routine, if one exists, 
for every device controller associated with the driver. 


e It calls the unit initialization routine, if one exists, for 
every device unit associated with the driver. 


13.1.2 Initialization During Recovery from a Power Failure 


During powerfail recovery procedures, the operating system locates 
every unit control block in the I/O data base. Each unit control 
block points to a channel request block for the device's controller. 
The channel request block contains the address of the controller 
initialization routine, if one was specified. The system uses’7 the 
following chain of pointers to locate the address of the 
initialization routine: 


DDB —» UCB —™ CRB —=s® controller initialization routine 


The operating system calls the initialization routine for each 
controller if one was specified in a DPT STORE macro for _ the 
CRBSL_INTD+VECSL INITIAL of the channel request block. 


Next, the system checks for a device unit initialization routine. 
First, the system examines the unit initialization field in the driver 
dispatch table (DDTSL UNITINIT). If the field does not contain an 
address, the system checks the channel request block using the 
following chain of pointers: 


DDB —= UCB —» CRB —™ device unit initialization routine 


MASSBUS drivers store unit initialization routines only in the driver 
dispatch table. 


If either the channel request block or the driver dispatch table 
contains a nonzero address for such a routine, the system calls the 
routine to initialize the device unit. 


S nenemenemmmaiiet 


1. The SYSGEN commands CONNECT and AUTOCONFIGURE call controller and 
unit initialization routines once for each controller and device unit. 
The LOAD command does not call controller or unit initialization 
routines, whereas the RELOAD command calls only the controller 
initialization routine. 
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13.1.3 Initialization Context 


The VAX/VMS operating system always calls controller and unit 
initialization routines with IPL raised to IPLS$ POWER. The high IPL 
prevents any interrupts from reaching the processor while 
initialization is occurring. The initialization routines must not 
lower IPL. The system calls initialization routines with a JSB 
instruction; the routines return by executing an RSB instruction. 


Controller initialization routines are device-dependent. For example, 


a card reader controller initialization routine might enable 
interrupts from the device by setting the interrupt enable bit in the 
device's control/status register. A disk controller initialization 


routine, on the other hand, might enable interrupts and initialize all 
unit status registers. 


If a device needs permanently allocated UNIBUS adapter resources, a 
controller initialization routine can call VAX/VMS UNIBUS adapter 


resource management routines to allocate the resources. Then, the 
initialization routine can set bits in the CRB UNIBUS adapter resource 
description fields (for example, VECSV_PATHLOCK in 


CRB$L_INTD+VECSB_DATAPATH) . 


At the time of a call to a controller initialization routine, the 
registers contain the following values: 


Register Value 

R4 Address of the control/status register 

R5 Address of the interrupt data block that describes 
the controller 

R6 Address of the device data block associated with 
the controller 

R8 Address of the channel request block for the 
controller 


Device unit initialization routines are useful for initializing 
device-dependent fields in the unit control block. For example, disk 
initialization routines can also set disk drive parameters (such as 
number of cylinders) in the unit control block and wait for online 
units to spin up to speed. Unit initialization routines must set’ the 
online bit in the unit control block (UCBSV ONLINE) to declare the 
unit to be online. — 


At the time of a call to a device unit initialization routine, the 
registers contain the following values: 


Register Value 
R3 Address of the primary control/status register 
R4 Address of the secondary control/status register; 


R4 is equal to R3 if there is no Secondary CSR 
R5 Address of the device's unit control block 
If driver initialization routines modify R4 through Rll, the routines 


must save the contents of the registers before use and restore them 
before returning to the operating system. 
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13.2 CANCEL I/O ROUTINE 


VAX/VMS routines call the cancel I/O routine in a device driver under 
the following circumstances: 


e When a process issues a Cancel I/O on Channel system service 


e When a process deallocates a device and no_ process I/0 
channels are assigned to the device 


e When a process deassigns a channel from a device 


e When the command language interpreter performs cleanup 
operations as part of image termination hy canceling all 
pending I/O requests’ for’ the image and closing all 
image-related files open on process I/O channels 

The VAX/VMS routine EXESCANCEL locates the unit control block for the 


device associated with a process I/O channel from a pointer in the 
channel request block, as follows: 


channel index number —». CCB —” UCB address 
EXESCANCEL takes the following steps: 
e Raises IPL to fork level 


e Removes all I/O request packets associated with the process 
from the device's I/O request packet wait queue 


e Sets the status code SS$_ CANCEL in IRPSL MEDIA 


e For buffered I/O read operation, clears the buffered read 
function bit (IRPSV_FUNC) in IRPSW_STS 


e Inserts the I/O packets removed from the packet wait queue 
into the I/O postprocessing queue 


e If the I/O postprocessing queue is empty, requests a_ software 
interrupt 


Then, EXESCANCEL calls the cancel I/O routine specified in the driver 


dispatch table of the associated device driver. EXESCANCEL locates 
the routine using the following chain of pointers: 


UCB —* DDB —=s DDT — sz address of the cancel I/O routine 


The cancel I/O routine gives the driver an opportunity to prevent 
further device-specific processing of the I/O request currently being 
processed on the device. 
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13.2.1 Context of a Cancel I/O Routine 


When EXESCANCEL calls the cancel I/O routine, IPL is at driver’ fork 
IPL so that the routine can read and modify the device's unit control 
block. Registers at the time of the call contain the following 
values: 


Register Value 
R2 Negated value of the channel index number 
R3 Address of the current I/O request packet 
R4 Address of the process control block of the 


process for which the Cancel I/O on Channel system 
service is heing performed 


R5 Address of the device's unit control block 


13.2.2 Drivers That Need No Cancel I/0 Routine 


Some devices do not need any device-dependent processing performed for 
an I/O request; you can omit the CANCEL argument from the DDTAB 
macro. In this case, the DDTAB macro expansion loads the address of 
the VAX/VMS routine IOCSRETURN into the appropriate position in the 
driver dispatch table. The routine IOCSRETURN executes a single RSB 
instruction. 


13.2.3 Device-Independent Cancel I/O Routine 


Drivers can specify the VAX/VMS routine IOCSCANCELIO as the value of 
the CANCEL argument in the DDTAB macro invocation. IOCSCANCELIO 
cancels I/O to a device in the following device-independent manner: 


e It confirms that the device is busy by examining the device 
busy bit in the UCB status word (UCBSV_BSY in UCBSW_STS). 


® It locates the process identification field in the I/O packet 
currently being processed on the device using the following 
chain of pointers: 


UCB —*™ IRP —™ process identification field 


IOCSCANCELIO confirms that the field (IRPSL PID) contains’ the 
same value as the corresponding field in the process control 
block (PCBSL PID). 


e It confirms that the specified channel index number is’ the 
same as the value stored in the I/O request packet channel 
index field (IRPSW_ CHAN). 


e It sets the cancel I/0 bit in the UCB status word 
(UCBSV_CANCEL in UCBSW_STS). 


Other driver routines, such as the device timeout routine, check’ the 


cancel I/O bit to determine whether to retry the I/O operation or 
abort it. 
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13.2.4 Device-Dependent Cancel I/0 Routines 


Drivers that include their own cancel I/O routines must perform the 
first three steps of IOCSCANCELIO listed in Section 13.2.3 to 
determine whether the I/O request being processed originates from the 
process canceling I/O on a channel. If the three checks Succeed, the 
cancel routine can proceed in a device-specific manner. 


13.3 ERROR LOGGING ROUTINES 

The operating system supplies two routines that drivers can call to 
allocate and fill error-logging buffers after a device error or 
timeout occurs: 

@e ERLSDEVICERR 

e ERLSDEVICTMO 

Both routines expect to find the address of the device unit control 
block in R5. Drivers must call them at fork IPL. Each routine 
performs the following steps: 

e It allocates an error log buffer of the length specified in 
the device's driver dispatch table. It uses the following 
chain of pointers to locate the buffer length: 

UCB —=™ DDB —=» DDT — length of error log buffer 


e It loads into the buffer fields from the unit control block, 
the I/O request packet, and the device data block. 


e It loads the address of the error message buffer location 
where device register contents are to be stored. 


e It calls a register dump routine in the device driver. Tt 
locates the routine using the following chain of pointers: 


UCB —= DDB —» DDT —*™ register dump routine address 


Specify the address of a register dump routine with the value of the 
REGDMP argument to the DDTAB macro invocation. 


The register dump routine can expect the following registers to be 
loaded: 


Register Content 
RO Address of the buffer 
R4 Address of the control/status register if the 


driver used the WFIKPCH macro to wait for an 
interrupt or timeout 


R5 Address of the device's unit control block 


The dump routine should save and restore R3 through Rll if the routine 
requires their uSe. 


13-6 


CODING INITIALIZATION, CANCEL I/0, AND ERROR-LOGGING ROUTINES 


The driver register dump routine should fill the buffer as follows: 


e Write a longword value representing the number of device 
registers to be written into the buffer 


@ Move device register longword values into the buffer following 
the register count longword 


The routine must store the contents of each device register to _ be 
logged in a longword in the buffer. For example, the following 
instruction stores the contents of the device register: 

MOV ZWL TD_STATUS (R4) , (RO) + 


A driver that supports error-logging must satisfy the following 
prerequisites: 


e It must use the error log extension to the unit control block. 
e It must ensure that DDTSW ERRORBUF is large enough to 
accommodate EMBSL_DV REGSAV+4 plus one longword for’ each 


register to be dumped | 


e Its driver prologue table must set the device characteristic 
DEVSV_ELG in UCB$_ DEVCHAR. 


13-7 


CHAPTER 14 


LOADING A DEVICE DRIVER 


You can load a user-written device driver any time after the system is 
bootstrapped. If the driver contains an error and the error does not 
crash or corrupt the operating system, you can correct the error and 
reload a new version of the driver. 


14.1 


IN PREPARATION FOR LOADING 


To prepare a device driver for loading, take the following steps: 


Write the device driver in one or more Source files. If the 
driver comprises multiple source files, you must insert a 
~-PSECT directive before any generated code in all files except 
the file that contains the DPTAB and DDTAB macro invocations. 
The following .~.PSECT must be used: 


~PSECT $$$115 DRIVER,LONG 


If a single source file contains the driver, you must not 
Specify any .PSECT directives. The declaration of the DPTAB 
and DDTAB macros establish driver program sections correctly. 


Assemble the source file(s) with the system macro library 
(SYSSLIBRARY:LIB.MLB). For example: 


$ MACKO MYNRIVER. MARFSYS#L. TRRARY ¢L18. ML B/L TRRARY 


Link the object file with the VAX/VMS' global symbol table, 
which is located in SYSSSYSTEM and called SYS.STB. If the 
driver consists of multiple source files, you must specify the 
file that contains the driver prologue table as the first file 
in the list. The linker options file must contain a_e BASE 
Statement specifying a zero base for the executable image. 
The following is an example of the creation of the options 
file and the LINK command used to link a driver: 


$ CREATE MYURIVER . OFT 

BASE =O 

CTALIZ) 

$ LINK /NOTRACE MYDRIVERTC sMYUR EVER 9 466 de 
MYDR IVER .OFT/OP TIONS 9 
SYS#SYSTEMSSYS.STR/SELECTIVE. SEARCH 


The resulting image must consist of a single image section. 
The linker will report that the image has no transfer address. 
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14.2 LOADING THE DRIVER 


Once the driver has linked correctly, it is ready to be loaded. To 
load the driver into system virtual memory, run the SYSGEN utility 
from the system manager's account or from an account having Change 
Mode to Kernel and Change Mode to Executive privileges using the 
following command: 


$ RUN SYS#SYSTEMZSYSGEN 
SYSGEN responds with a prompt and waits for further input: 

SYSGEN> 
The VAX/VMS System Manager's Guide describes the full set of SYSGEN 
commands. The sections that follow describe those commands SYSGEN 


uses to load drivers: 


e LOAD (requires Change Mode to Kernel (CMKRNL) and Change Mode 
to Executive (CMEXEC) privileges) 


e CONNECT (requires CMKRNL and CMEXEC privileges) 
e RELOAD (requires CMKRNL and CMEXEC privileges) 
e@ SHOW/DEVICE (requires CMEXEC privilege) 


In addition, you should understand SYSGEN's automatic configuration 
feature, as described in Section 14.3. 


14.2.1 LOAD Command 


To load a device driver and its data base, issue the LOAD command. If 
the controller has only aesingle unit attached to it, issue the 
CONNECT command. 


Format 
LOAD driver-file-spec 


driver-file-spec 
The file specification of the image file containing the I/0 
driver to be loaded. If the driver file specification is the 
same as the driver name of a loaded driver, the LOAD command has 
no effect. 


SYSSSYSTEM is the default device and directory name. EXE is’ the 
default file type. 


Description 
The driver loading procedure compares the name field in the 
driver prologue table of the driver being loaded with the name 
field in the driver prologue tables of the drivers already loaded 
into system memory. If no match is found, the procedure loads 
the new driver into contiguous pages of nonpaged pool and links 


the driver prologue table into the DPT linked list. If the 
procedure finds a match, it takes no further action. 


Example 
SYSGEN> LOAD CRIRIVER 
This command loads the card reader driver. 
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14.2.2 CONNECT Command 


The CONNECT command creates I/O data base control blocks for devices. 
The CONNECT command can also load the driver if it has not been 
previously loaded into system memory. 


Format 
CONNECT device-name required-quals [optional-quals] 
Command Qualifiers 


/ADAPTER=tr-value 

/CSR=csr-address 
/VECTOR=vector-address 
/DRIVERNAME=driver-name (optional) 
/NUMVEC=number (optional) 
/ADPUNIT=unit-number 
/MAXUNITS=number 


Parameter 
device-name 


The name of the device for which control blocks are to be added 
to the I/0 data base. Specify the device name in the following 


format: 
devcu 
dev device code (up to 9 alphabetic characters) 


Cc 
u 


controller designation (alphabetic) 
unit number (in the range of O through 7) 


For example, LPAO specifies the line printer (dev) on controller 
A (c) at unit 0O (u). When specifying the device name, do not 
follow it with a colon (:). 


The device code and controller specification must be a unique and 
accurate device name and controller combination. If control 
blocks for the specified device/controller already exist, the 
driver loading procedure does not create any control blocks. If 
the device/controller name does not accurately name a device, the 
procedure will create spurious control blocks. 


Required Qualifiers 


/ADAPTER=tr-value 
The number of the SBI arbitration priority to which the UNIBUS or 
MASSBUS adapter is attached. The tr-value must be in the range 
of 0 through 15. All numeric values are interpreted as decimal 
unless they are preceded by a radix descriptor (%0O or %X). 


/CSR=csr-address 
The UNIBUS address of the control/status register for the device. 
All numeric values are interpreted as decimal unless they are 
preceded by a radix descriptor (%0 or $%X). 


/VECTOR=vector-address 
The UNIBUS address of the interrupt vector for the device. All 
numeric values are interpreted as decimal unless they are 
preceded by a radix descriptor (%0 or %X). Section 14.3 provides 
additional information on vector and CSR assignments. 
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Optional Qualifiers 


/NUMVEC=number 
The number of interrupt vectors for the device. If this 
qualifier is omitted, the number of vectors defaults to l. The 
number specified by the /VECTOR qualifier is the address of the 
lowest vector. Vectors muSt be contiguous. 


/DRIVERNAME=driver-name 
The name of the driver as recorded in the driver prologue table. 
If the driver is not loaded when the CONNECT command is issued, 
CONNECT assumes the driver name is also the file name of an 
executable image that is located in SYSSSYSTEM and contains a 
driver for the device type. 


Consult the SYSGEN device table in Section 14.3.2 for the driver 
names of the devices supported by VAX/VMS. 


/ADPUNIT=unit-number 
The unit number of a device on the MASSBUS') adapter. The unit 
number for a disk drive is the number of the plug on the drive. 
For magnetic tape drives, the unit number corresponds to the tape 
controller number. 


/MAXUNITS=number 
The maximum number of units attached to the system. This number 
determines the size of the UCB list appended to the interrupt 
dispatch block. If specified, this value overrides the maximum 
number of units designated in the driver prologue table. The 
maximum number of units is stored in the IDB field IDBSW_UNITS. 


Description 


The I/O data base contains a linked list of driver prologue 
tables. The CONNECT command looks for a device driver by 
comparing the specified or defaulted name with the driver names 
in the driver prologue tables. If the driver is not present, the 
driver loading procedure opens the driver image and loads’7 the 
file contents as it does for the LOAD command; see Section 
14.2.1. 


Then the loading procedure examines the I/O data base for control 
blocks that support the specified device. The procedure creates 
the following control blocks if they do not exist: 


e Device data block -- the procedure creates a device data block 
for the generic device name/controller string specified if 
such a device data block does not exist. 


When the procedure creates a device data block for a UNIBUS 
device, it also creates a channel request block and an 
interrupt data block. 


e Unit control block -- the procedure creates a unit control 
block if it has just created a device data block or if a unit 
control block for the specified device does not exist. 


After creating the control blocks, the driver loading procedure 
initializes fields in the control blocks according to the driver 
prologue table. Since the control blocks describe devices new to 
the system, the procedure writes fields specified in both the 
initialization and reinitialization portions of the driver 
prologue table. 
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If the driver loading procedure just created a channel request 
block and the driver specifies device unit and/or controller 
initialization routine addresses in DPT_STORE macro invocations 
(CRBSL INTD+VECSL INITIAL and CRBSL INTD+VECSL UNITINIT), the 
driver loading procedure calls these initialization routines for 
units and controllers represented by newly created control 
blocks. The procedure raises IPL to 31 before calling the 
routines so that initialization is not interrupted. 


You Should specify CONNECT commands with extreme caution. The 
driver and data base loading procedure does little error 
checking. If the user specifies a vector that has already been 
defined, the procedure rejects the CONNECT command. However, if 
the CONNECT command specifies an incorrect CSR address, the I/0 
data base is apt to become corrupted. The result is a system 
failure. 


If the CONNECT command specifies an existing controller and a new 
device unit, the procedure creates a unit control block for the 
new unit and calls a unit initialization routine for the unit. 


A CONNECT command that specifies a device name with a new 
controller causes the driver loading procedure to create a device 
data block, channel request block, interrupt data block, and unit 


control block and to call controller and unit initialization 
routines. 


Example 
SYSGENS CONNECT LEFAQ /ANAPTER®3 /OSR=“407773514 /VECTOR=Z0200 
This command loads the driver LPDRIVER, if it is not already 


loaded, and creates the device data base (DDB, CRB, IDB, and UCB) 
needed to describe LPAO. 


14.2.3 RELOAD Command 


The RELOAD command loads a driver and removes a_ previously-loaded 
version of that driver. The RELOAD command provides all of the 
functions of LOAD, except that it loads the driver regardless’ of 
whether it is already loaded. 


If any of the units associated with the driver are busy, the driver 
cannot be reloaded; SYSGEN issues an error message. 


Format 
RELOAD driver-file-spec 

driver-file-spec 
The file specification of the image file containing the driver to 
be loaded. 

Description 
To reload the driver, the driver loading procedure compares’ the 
name field in the driver prologue table of the driver being 
loaded with the name field in the driver prologue tables of 


drivers already loaded into system memory. If no match is found, 
RELOAD loads the driver as described in Section 14.2.1. 
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If the procedure finds a match, it first confirms that the 
current driver can be replaced by the new driver in the following 
steps: 


e Confirms that the DPTSM NOUNLOAD flag in the driver prologue 
table of the current driver is not set 


e Calls the current driver's unload routine, if one exists, and 
confirms that the returned status is a success code 


e Ensures that no devices that use the current driver are busy, 
as indicated by the UCBSV_BSY bit set in UCBSW_STS 


If these checks succeed, the procedure replaces the current 
driver with the new driver. The procedure loads the new driver 
into contiguous pages of nonpaged system memory and searches’ the 
I/O data base for references to the driver. If any device data 
block refers to the driver being reloaded, the procedure 
reinitializes fields of the device and controller control blocks 
according to the reinitialization instructions in the new 
driver's prologue table; Chapter 7 describes the DPT 
reinitialization fields. 


Fields that must be reinitialized when a driver is7 reloaded 
include those that contain relative addresses within the driver: 


e Addresses of driver interrupt service routines 


e Addresses of device unit and controller initialization 
routines 


e Address of the driver dispatch table 


Once the loading procedure has reinitialized fields, it calls the 
driver controller initialization routine. (It does not call the 
unit initialization routine.) The procedure then removes’ the 
newly replaced driver from the DPT list and deallocates the 
nonpaged system space the old driver occupied. Finally, the 
loading procedure links’ the address of the new driver prologue 
table into the DPT list. 


14.2.4 SHOW/DEVICE 


The SHOW/DEVICE command displays the location of a driver and the I/0 
data base describing its devices in system virtual memory. This 
command requires Change Mode to Executive privilege; Change Mode to 
Kernel will not suffice. 


Format 
SHOW/DEVICE [=driver-name ] 
driver-name 
Name of the driver for which the information is to be displayed. 


If a driver name is not specified, the command displays 
information about all drivers and devices known to the system. 
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Description 
The SHOW/DEVICE command displays the following information: 
e Name of the driver 


e The driver's starting and ending virtual addresses; the 
starting address is the address of the driver prologue table 


e The generic device/controller name associated with the driver 


e The addresses of the device data block, channel request block, 
and interrupt data block for the generic device/controller 
Supported by the driver 


e The unit numbers and UCB addresses for each device unit 
associated with the driver 


Example 
SYSGEN? SHOW/DEVICE= TMOR IVER 
ates UP Rn TR Tas ceeue S NETB sn ce CPE Yn ese TOTES ssn ses tet oe PR TES coe sn soe ne see ee Le OUER eecseeee ee ane oe IND Te IO 


TMOURTIVER 80090RF00 BQO9F O20 
MTA BOOBAGSO BOOKASCO BOOKAS4GO 
O BOOPF ORO 
L B8Q09FOCO 


14.3 AUTOCONFIGURATION 


The standard VAX/VMS system start-up file runs the SYSGEN utility to 
create and initialize an I/O data base that describes all supported 
DIGITAL peripherals in the configuration. The following command 
requests the SYSGEN utility to prepare a data base for all supported 
DIGITAL devices attached to every UNIBUS and MASSBUS: 


SYSGEN> AUTOCONFIGURE ALL 


To configure devices attached to the UNIBUS, SYSGEN goes’ through’ the 
steps described in subsequent sections of this chapter. 


DIGITAL-sSupported devices are attached to the UNIBUS according to a 


table found in Appendix A of the PDP-11 Peripherals Handbook. The 
basic rules follow: 


e A device of type A is always at a fixed and predefined CSR 
address; the device always interrupts at a fixed and 
predefined vector address; only one example of device A_ can 
be configured in each system. 


e A device of type B is identical to type A except that Il 
through n examples can be configured ina single system. 
Examples 2 through n are also located at fixed and predefined 
CSRs and vector addresses. 


e Devices of type C (1 through n of them) are always at fixed 
and predefined CSR addresses; however, the interrupt vector 


addresses vary according to what other devices are present on 
the system. 


e Devices of type D (1 through n of them) are at CSR _ addresses 
and vector addresses that vary according to what other devices 
are present on the system. 
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The CSR and vector addresses that vary are called floating addresses. 
The devices must be located in floating CSR and vector space according 
to the order in which the devices appear in the SYSGEN device table. 
This table, shown in Section 14.3.2, lists all the type A and type B 
devices supported by VAX/VMS. It also lists the type C and type OD 
devices that are recognized by SYSGEN's autoconfiguration procedure. 


The base of floating vector space is 300 (octal). The base of 
floating CSR space is 760010 (octal). 


14.3.1 SYSGEN's Autoconfiguration 


The SYSGEN utility automatically configures a UNIBUS adapter as 
follows: 


e It initializes the base of floating space to 300 (octal) and 
760010 (octal) for vectors and CSRS, respectively. 


e It tests fixed and floating CSR address space for all known 
DIGITAL devices. 


e When a device is found at a CSR, SYSGEN reserves floating CSR 
and vector space for that device, if necessary. Then, if the 
device is supported by VAX/VMS, SYSGEN creates and initializes 
an I/O data base for that supported device and loads the 
driver for that device. 

The SYSGEN utility uses a table that lists the characteristics of all 
DIGITAL devices. This table indicates the following information for 
each device type: 

e The device controller name 

e The name of the device driver, and whether it is Supported 

e The name of the device recognized by VAX/VMS 

e The interrupt vector 

e The number of interrupt vectors per controller 

e The address of the first device register for each controller 
recognized by SYSGEN (the first register is usually, but not 
always, the CSR) 


e The number of registers per controller 


14-8 


14.3.2 The SYSGEN Device Table 


Currently, the SYSGEN device table lists the following devices: 


Name 


CR1i1l 
RK6 11 


LP1l 


RL211 
(controller A) 


TS11 
(controller A) 


RX211 


DC1l 


Vector 


230 
210 
200 
170 
174 
270 
274 


160 


224 


264 


float 


#Vectors 


Vector 


Alignment 


CSR/Rank 


777160 
777440 


777514 
764004 
764014 
764024 
764034 


774400 


772520 


777170 


774000 
774010 
774020 
774030 


(maximum of 
32 units) 


#Registers 


Driver 
Support 


CRDRIVER 
DMDRIVER 


LPDRIVER 


DLDRIVER 


TSDRIVER 


DYDRIVER 


no 


VAX/VMS 
Device Code 


CR 
DM 


LP 


DL 


MS 


DY 


YFAIHYC FJOIAMG WV ONICVOT 


OT-?I 


Name 


KL11 or 
DL11A/B 
(controllers 
ByCyreee) 


DN11 


DMB11 


DRII1A or 
DR11C 


Vector #Vectors 


Float 2 
float 1 
Float 1 
float 2 


Vector 
Alignment 


Driver 
CSR/Rank #Registers Support 


776500 no 
776510 no 
776520 


(maximum of 
16 units) 


775200 no 
775210 
775220 


(maximum of 
16 units) 


770500 no 
770510 
770520 


(maximum of 
16 units) 


767600 no 
767570 
767560 


(maximum of 
16 units) 


VAX/VMS 
Device Code 


YHATYC FOTIA YW ONIGWOT 


Tl-oT 


Name 


PR611 


PP611 


DTI1 


DX11 


DL11C/D/E 


Vector 
Vector #Vectors Alignment 


float 1 8 
float 1 8 
float 2 8 
float 2 8 
float 2 8 


CSR/Rank 


772600 
772604 
772610 


(maximum of 
8 units) 


772700 
772704 
772710 


(maximum of 
8 units) 


774200 
774202 
774204 


(maximum of 
8 units) 


776200 
776240 
776300 
776340 


775610 
775620 
775630 


(maximum of 
28 units) 


Driver 
#Registers Support 


no 


no 


no 


no 


no 


VAX/VMS 
Device Code 


YZATYd AOIAGG W ONIAVOT 


Vector Driver VAX/VMS 


ct-vl 


Name Vector #Vectors Alignment CSR/Rank #Registers Support Device Code 
DJ11 float float no 
DH11 float float no 
GT40 Float 772000 no 
772010 
LPS1l1l float 770400 no 
DQ11 float float no 
KW11W Eloat 772400 no 
DV11l float float no 
DVP11 Eloat float no 
DV11 Float 775000 no 
775040 
775100 
775140 
LK11 float Float no 
DMC11 Float Float XMDRIVER XM 
DZ11 float float DZDRIVER ded 
KMC11 Float float no 
LPP1l1l Eloat float no 
VMV21 Float float no 
VMV31 Float float no 
DWR 70 Float float no 


YGATYG dOTAad W ONIAWOT 


€Ct-vI 


Name 


RLZ1l1 
(controllers 
By,Cyeoe) 


TS1l 
(controllers 
B,Cyeee) 


LPA11 


KwW11ic 


RX11 
(RXO1) 


DR11 
DR11B 


Vector 


float 


float 


float 
float 


float 


float 


float 
124 

float 
float 


#Vectors 


2 
2 


2 


**CSR Position 17, Reserved, 


1 


Vector 
Alignment 


8 
8 


8 


4 


CSR/Rank 


float 


772524 
772530 
772534 


770460 
float 


float 


float 


float 
772410 
772430 
float 


#Registers 


8 
4 
4 Registers** 


4 


Driver 
Support 


DLDRIVER 


TSDRIVER 


LADRIVER 
LADRIVER 


no 


no 


no 


no 
no 


VAX/VMS 


Device Code 


DL 


MS 


LA 
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Devices not listed in the SYSGEN device table include: 


e Non-DIGITAL-supplied devices with fixed CSR and vector 
addresses. These devices have no effect on autoconfiguration. 
Customer-built devices should be assigned CSR and vector 
addresses beyond the floating address space _ reserved for 
DIGITAL-supplied devices. 


e Those DIGITAL-supplied, floating vector devices that’ the 
AUTOCONFIGURE command does not’ recognize. Use the CONNECT 
command to attach these devices to the system. 


14.3.3 Floating Vector Address Calculation 

To calculate the floating vector address of a device, the SYSGEN 
utility rounds the current floating vector base (CFVB) up to the next 
valid vector address boundary for the next device in the table. 


If a device is present, SYSGEN reserves floating vector space for’ the 
device by computing a new CFVB: 


CFVB + (4 * number of vectors) — »— CFVB 


14.3.4 Floating CSR Address Calculation 

To calculate the floating CSR address of a device, SYSGEN rounds” the 
current floating CSR base (CFCB) up to the next valid floating CSR 
address. Floating CSR addresses must fall on an 8-byte boundary. 
SYSGEN tests the CSR address (CFCB) for the next device in the device 
table by executing a test word (TSTW) instruction on the address and 
noting whether there is a response at that address. 


If the device is present, SYSGEN reserves floating CSR address’ space 
for the device by computing a new CFCB: 


CFCB + bytes in register set — CFCB 
When all devices of a particular type have been located and their 
floating CSR space reserved, SYSGEN reserves an extra block of CSR 
Space to indicate a change to a new device type: 


CFCB + 8 —»™CFCB 


If the device is not present, SYSGEN reserves an extra block of CSR 
Space to indicate a change to a new device type: 


CFCB + 8 —™ CFCB 


14.3.5 Rules for Configuration 


The equations described in Sections 14.3.3 and 14.3.4 reduce to the 
following maxims: 


e Devices with fixed CSR addresses and fixed vector addresses 


must be attached according to the SYSGEN device table 
settings. 
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e Devices with floating CSR or vector addresses must be attached 


in the order in which they are listed in the SYSGEN device 
table. 


@ An 8-byte gap must be reserved between each different type of 
device that is located in floating CSR address space. 


e An 8-byte gap must be reserved in floating CSR address’ space 
for each device type that has no controller in its 
configuration. 


e An extra 8-byte gap muSt be reserved between the KW1I1C and the 
RX1ll in floating CSR address space, 


14.3.6 Example of a UNIBUS Configuration 


This example shows the correct configuration for UNIBUS devices’ with 
floating CSR and vector addresses. Controllers flagged with an 
asterisk (*) are not supported by DIGITAL. 


Controller Vector (s) CSR (first register) 
1 DN11* 300 775200 
1 DU11* 310 760040 
1 DV1l1l* 320 775000 
1 DMC1ll 340 760100 
2 DZlls 350 760120 
360 760130 
2 TSlls 224 772520 
370 772524 
3 DR11Bs* 124 772410 (CSR is third register) 
400 772430 
410 760260 
l customer 420 760320 
device (or higher) (or higher) 


When assigning floating vector addresses and registers to devices not 
supplied by DIGITAL, be sure to leave a generous gap between these 
addresses and those of DIGITAL devices, since subsequent VAX/VMS 
maintenance updates may add new devices to the SYSGEN device table. 
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CHAPTER 15 


DEBUGGING A DEVICE DRIVER 


DELTA and XDELTA are debugging tools that can be used to monitor’ the 
execution of user programs and the VAX/VMS operating system. When you 
link DELTA with a uSer image that runs in a nonprivileged process, 
DELTA iS a user-mode debugging tool. When run ina privileged 
process, however, DELTA acts as a multimode debugger; it allows you 
to debug in user mode or to change to kernel mode for debugging. 
DELTA does not Support debugging at elevated IPLs. 


XDELTA is syntactically identical to DELTA but also allows you _ to 
debug code that executes at an elevated IPL. XDELTA is used for 
Stand-alone debugging of driver code and the executive. 


In the command syntaxes and dialogues contained in this chapter, red 
ink indicates the commands typed by the user and black ink indicates 
the system prompts and responses. 


15.1 BOOTSTRAPPING THE SYSTEM WITH XDELTA 


Under VAX/VMS, drivers are part of the operating system. You normally 
bootstrap the system with two boot flags set to allow you to debug 
with XDELTA. One flag causes the bootstrapping procedure to include 
XDELTA in the- system. The other boot flag indicates a stop at a 
breakpoint in VAX/VMS initialization. Execution of the breakpoint 
instruction causeS control to transfer to a fault handler located in 
XDELTA. 


In addition to the normal system bootstrap command files, the VAX/VMS 
console floppy diskette contains two command files that hootstrap the 
system with XDELTA: 

@ DMAXDT 

e DBAXDT 


To bootstrap the system with XDELTA, follow the procedures in the 
VAX-ll Software Installation Guide with two exceptions: 


e Deposit the unit number of the device in R3. 


e Specify one of the command files listed above instead of the 
command files listed in the installation guide. 


The dialogue in Figure 15-1 is an example of bootstrapping the system 
with XDELTA. 
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SS sTEFOSTT R3 oO Deposit the unit number in R3. 


oS @0MAXIT Boot the system from DMAOQ. The 
procedure boots the processor. and 
prompts the user from SYSBOOT. 


SYSROOTS USE 1T6USER. PAR Specify a parameter file for the 
system. 
SYSROOTS SET BUGREBOOT © Request an XDELTA breakpoint after a 


system bugcheck. 
SYSBOOTS CONTINUE Continue with the booting operation. 
Figure 15-1 Bootstrapping the System with XDELTA 
After being bootstrapped, the system displays its welcoming message 
and halts in XDELTA, as follows: 
1 BRK AT nnonnnnnn 


XDELTA is waiting for input. (XDELTA never issues explicit prompts.) 
Usually, you proceed from this point with the following command: 


i RET 
All of the XDELTA commands are described in Section 15.10. 
If the operating system halts with a fatal bugcheck, the system prints 
the bugcheck information on the console terminal. Then, because the 
System parameter BUGREBOOT was set to zero, XDELTA prompts. Bugcheck 
information consists of the following: 

e Type of bugcheck 

e Register values 

e Dump of one or more stacks 
PC and stack content indicate how an experimental driver crashed the 


system. You can then examine the system state further by issuing 
XDELTA commands. 


15.2 LOADING THE DRIVER 


Once the system is running, you can log in to the system as the system 
manager and load the experimental driver. 


To load the driver, run the SYSGEN utility and issue the appropriate 
LOAD and CONNECT commands. Figure 15-2 provides a sample dialogue. 


The first SHOW command in Figure 15-2 causes the SYSGEN utility to 
display the location of the device driver in System memory. You then 
define the device to the operating system. The second SHOW command 
causes SYSGEN to display the driver's location and the addresses of 
the device's DDB, CRB, IDB, and UCB. 


Lo=2 


$ FUN 
SY SGENS 


SYSGEN> 


Sr iriver... 


YROR IVER 
SYSGENS 


SY SGENS 


we LI POL VG@ 1h .. 


YRORTVER 


Cy 


SYSGENS 
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The SYSGEN command CONNECT calls controller 
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SYS#SYSTEM 3 SYSGEN 
. 


OAT MAGS TC YOUR. DIRECTORY TY ROR IVER «EXE 
SHOW /TEVICK=YROR IVER 
eee aren 2 = eeemmermaces |g) (a case) 0s « Career 
BOOS6OESO 80061070 
CONNECT YR /ATIAP#® 3/VEC#A02 74 /CSRE AD? ZO6R240 
SHOW /TEVICK = YROR IVER 
sealer Gat Utter BIE a toae OV aot LNB indicia GM Romer UB aoe IIE Gam C Bes ctead 
BOO6OESO BO061070 
O SO060RRK0 

EXIT 


Figure 15-2 Loading a Driver 


INSERTING BREAKPOINTS IN THE SOURCE CODE 


initialization and unit 


initialization routines. To begin debugging the driver, you should 
ensure that the kernel mode debugging utility XDELTA gains control of 
the driver before these routines execute. This is accomplished by 
placing calls to the special system routine INISBRK within the source 
code of either the controller or unit initialization routines. To 
call INISBRK, give the following instruction: 

JSB G* INISBRK 
The INISBRK routine contains two instructions: 

BPT 

RSB 
When the processor executes the BPT instruction, XDELTA gains’ control 
and reports the address of the breakpoint: 

1 BRK AT nnnnnnnn 
You can use INISBRK aS a debugging tool and place calls to it within 
any part of the driver source code. 
To determine the last driver PC before the breakpoint, examine’ the 


kernel stack. 


The stack register is register RE (hexadecimal format): 


RiE/address /address 


Display RE to find the address of the current top of 
command 


display 


Another 
that is, 


stack. 
reveals the contents of the stack top, 


(7) 


the return address to the driver that called INISBRK. 
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15.4 CALCULATING THE BASE OF DRIVER CODE 


Before you debug the driver, it is a good idea to calculate the base 
address of driver code, as follows: 


@e Run the SYSGEN utility and issue the SHOW/DEVICE command. The 
resulting display lists the location in nonpaged pool at which 
SYSGEN loaded the driver. 


e Consult the load map for the driver (obtained at driver link 
time). The driver resides in two program sections (PSECTs): 


$$$105 PROLOGUE driver prologue table 
$$$115 DRIVER driver code 


The locations given in the driver code listing are offsets 
from $$$115 DRIVER. Thus, you can calculate the base address 
of the driver by adding the address at which the driver was 
loaded to the offset associated with the PSECT $$$115 DRIVER 
shown in the map. ~ 


If you do not have the load map, consult the driver prologue table in 
the driver listing. Look for the address of DPT STORE END, which 
generates a 2-byte entry that terminates the DPT. To get the base 
address of driver code, add the address of DPT STORE END + 2 to the 
address at which the driver was. loaded. You can set an XDELTA 
relocation register to the base of driver code; Section 15.7 
describes this procedure. 


15.5 REQUESTING AN XDELTA SOFTWARE INTERRUPT 


Once the controller and unit initialization routines complete 
execution, you will need to set breakpoints in order to debug the 
driver. You can set a breakpoint in the driver source code by 
inserting calls to INISBRK, as described in Section 15.3. You can 
also invoke XDELTA to set breakpoints interactively by requesting an 
XDELTA software interrupt. At the console terminal, issue_ the 
following commands: 





SeSQEPOSIT/T 14 3 

2 CON TINUE 
The above procedure issues a software interrupt to the processor at 
IPL 5. The IPL 5 interrupt service routine handles the interrupt by 
calling the routine INISBRK, which in turn executes the first XDELTA 
breakpoint. XDELTA then issues the message: 


lL BRK AT nnnnnnnn 
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15.6 LOOKING AT THE VECTOR JUMP TABLE 


To gain experience in looking around the I/O data base, you may wish 
to look for the address of the location in the channel request block 
that contains a JSB instruction to the driver's interrupt service 
routine. You can do this at a controller initialization breakpoint 
because one of the inputs is the IDB address: 


RS /IDB-address Q4C/ADP-address 

Q+10/vector-table-address 
Q+vector-address-~in-hex/address-of -JSB-instruction-in-CRB 
Q/ JSB-instruction 


Finding the driver interrupt Service routine address at the expected 
vector does not guarantee that an interrupt from the device will 
dispatch to the driver's interrupt service routine. If the device's 
physical vector is set to some other address, an interrupt from the 
device may dispatch to some other interrupt service routine, or 
dispatch to an unasSigned vector. 


See the SYSGEN device table shown in Chapter 14 for a list of vectors. 


Consult field service for help with any problem similar to the one 
described above. 


15.7 SETTING AN XDELTA BASE REGISTER 

During a driver debugging session, you can uSe an xXDELTA relocation 
register aS a base from which to examine driver code and set 
breakpoints within the driver. Use one of the methods outlined in 
Section 15.3 to determine the base address of driver code, then set a 
relocation register by issuing the following command: 


1. BRK AT nnnnnnnn 
driver-base-addressy(Q3X 


This command sets relocation register X0 to the base of driver code. 
Now you can examine offsets into the code using X0 as a base: 


XO + of fSet/nnnnnnnn 
To set breakpoints in driver code, give the command: 
XO + of fsetsk 


To display a driver instruction, add the instruction's offset to the 
base register, for example: 


XO4+1.C0/ instruction ook 


The last XDELTA command sets a breakpoint at the displayed location. 
See Section 15.10 for a detailed discussion of XDELTA commands. 


15.8 DESTROYING REGISTER CONTENTS 


Since much driver code calls VAX/VMS I/O routines, you must be careful 
to anticipate the register usage of these routines. Most VAX/VMS 
common I/O support routines use RO through R3_ freely. A frequent 
driver bug iS to load a value into R3 and expect to find it intact 
after a call to allocate or load UNIBUS adapter resources. 
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Other VAX/VMS I/O routines write into R4. In some cases, the use of 
R4 is obvious; for example, IOCSREQSCHANL writes the device's CRB 
address into R4. In other cases, you might not anticipate the use of 
R4, 


For example, EXESIOFORK saves the calling code's R4 in a_ fork block, 
and then writes the device's IPL into R4. Since the normal flow of 
events is that an interrupt service routine restores a driver with a 
JSB instruction and the driver then calls EXESIOFORK which returns to 
the interrupt service routine, the instructions following the JSB_ in 
the interrupt service routine can only assume R5 is still untouched. 
The coding sequence is as follows: 


; Restore R3-R4. 
JSB @UCBSL_ FPC(R5) ; Restore the driver process. 


Between these instructions, the interrupt service routine can make no 
assumptions about the contents of RO through R4 


POPR #M"~<RO,R1,R2,R3,R4,R5> ; Restore interrupt registers. 
REI ; Return from the interrupt. 


15.9 EXAMINING UCB, IRP, AND PSL 

In addition to using XDELTA to debug drivers, you alSo can examine the 
contents of the unit control block and the associated I/O request 
packet. 

It also is useful to examine the contents of the PSL at the time of a 
system failure. The PSL, for example, indicates the IPL at the time. 
When the system fails it prints the PSL and other register contents on 
the console terminal. 


While the system is running, the following command can be used _ to 
examine the PSL in XDELTA: 


RE +4 / 


That is, the PSL location is stored in the longword following the PC. 


15.10 XDELTA COMMANDS 


Table 15-1 summarizes XDELTA commands. The sections that follow 
detail the commands. 
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Table 15-1 
XDELTA Command Summary 


Command Function 


a ohh haan is be cm PARRA erent — soe mite et ema ne 











Open location 

Close current location 

Close current location; open next 

Open location specified by current value 
Display previous location 

Display value of expression; set Q 


It (fi 30 a™ 
389 B 


Add 

Subtract 

Add 

Multiply 

Shift 

Divide 

Field separator 

Last quantity displayed 

Register n 

Base register hn 

Processor register n 

Add *X80000000 to subsequent or preceding value 
Add *“X7FFE0000 to subsequent or preceding value 
Current location 


+ 
Ss 
* 
@ 
% 


Execute one instruction 

Proceed from breakpoint 

Set/clear/display breakpoint 

Execute command string 

Go to location and proceed 

Set base register 

Set byte mode 

Set word mode 

Set longword mode 

Set ASCII mode 

Deposit string at current dot, autoincrementing dot. 
A single quote terminates the string; any (@&s and 
@s typed will be stored. 


yn 


=e Se Oe C6 We 





15.10.1 Values and Expressions 
All numeric values are interpreted in hexadecimal radix. Expressions 
are Strings of alternating values and binary operators, where the 
first and last items in the string are always values, as in the 
following example: 

GAAS? + 24 - 4 


Trailing operators are ignored. 
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15.10.2 Special Symbols 


XDELTA defines the following special symbols: 


P Current location; set by slash (/) and TAB 
operations 

@) Last quantity displayed 

X0—>-XF Base registers; used for remembering values 

RO—RF General register names 

PO0—2=Pnn Internal processor registers 

RF+4 PSL 

G “X80000000; prefix for system space addresses; 


for example, G2E is equivalent to “X8000002E 


H “X7FFE0000; prefix for control region prefix; for 
example, H2E is equivalent to “X7FFE002E 


15.10.3 Operators 
XDELTA recognizes the following operators: 
+ or space add 


~~ negate, subtract 


* multiply 
% divide 
@ Shift (arithmetic) 


Evaluation of expressions is left to right with no precedence. 


15.10.4 Open and Display Command 
Syntax 
address expression/old value [new value expression] (RET) 


You can type an address expression followed by a slash (/) character. 
XDELTA displays the contents of the location (old value above) 
followed by a space character. You can change the value at the 
location by typing a new value followed by return ( @& ). If you 
type a carriage return not preceded by a value, the old contents 
remain unchanged. 


The display and the value deposited default to longword hexadecimal 


values. The length can be changed to byte or word with the set mode 
commands. 
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A slash preceded by a null address expression uses the displayed value 
(Q) as the address value. This feature is convenient for following 
address linked chains. 


address _expression/old value /old value /old value 


15.10.5 Close and Display Next Location Command 
Syntax 

(LF) 
Press the line feed key (@ ). XDELTA closes the current open 
location, then opens and displays the value in the next location 
according to the current display mode. Next location is calculated to 


be the current location counter increased by the current data width 
(byte, word, or longword). 


15.10.6 Display Range Command 
Syntax 
Start_addr_expression,end addr _expression/contents of start 
Type two address expressions Separated by a comma and followed by a 
slash (7) character. XDELTA displays the range of addresses 


specified; the location counter is increased by the current display 
width; the contents of each location is displayed in the current data 


type. 


15.10.7 Indirect Command 
Syntax 
TAB) 
Press the (A) key. XDELTA uses the result of the last display 


operation (Q) aS an address and displays the contents of that address 
according to the current display width and data type. 


15.10.8 Display Previous Location Command 
Syntax 


ESC 


Press the €8 key. XDELTA decreases the location counter by the 
current display width, and displays the contents of the resulting 
address according to the current display width and data type. 
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15.10.9 Show Value Command 
Syntax 

expression=value of expression 
Type an expression followed by an equal sign (=). The expression can 
be composed of a series of values and operators from the set of 
operators listed in the command summary. XDELTA shows’ the value of 


the expression according to the current display data type. The last 
quantity (Q) is set to the value of the computed expression. 


15.10.10 Step Instruction Command 
Syntax 
5 
Type an S. XDELTA causes one instruction to be executed and then 


displays the address of the next instruction and its contents at the 
current display width and data type. 


15.10.11 Setting Breakpoints 
Syntax 

address-expression;B RET)! 
Specify an address followed by a sSemicolon (;) the letter 8B, and 
return ( @&M ). XDELTA sets a breakpoint at the specified location 
and assigns it the first available breakpoint number. 
Alternate syntax: 

address~expression,n;B RET 
Specify an address, followed by a comma, a Single digit between 2 and 
8, a semicolon (;), the letter B, and return ( ft)? ). XDELTA Sets a 


breakpoint at the specified location and assigns it the _ specified 
breakpoint number. Breakpoint 1 is reserved for INISBRK. 


15.10.12 Clearing Breakpoints 
Syntax 
Ones RET 
Type zero (0), followed by a comma, a Single digit between 2 and 8, a 


semicolon (;), the letter B, and return ( @& ). XDELTA clears the 
specified breakpoint. Never clear breakpoint l. 
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15.10.13 Displaying Breakpoint List 
Syntax 

7B 
Type a semicolon (;) followed by the letter B. XDELTA shows’ the 
current setting of all breakpoints. For each breakpoint, XDELTA 
displays the following information: 

e Breakpoint number 


e Address at which the breakpoint is set 


e Display address (for complex breakpoints; see Section 
15.10.19) | 


e Command string address (for complex breakpoints) 


15.10.14 Setting Base Registers 
Syntax 

address-expression,n;X 
Type an expression followed by a comma (,), a Single digit between 0 
and D (hexadecimal), a semicolon (;), and the letter X. XDELTA 
assigns the specified expression to the base register selected by n. 
Base registers E and F are preassigned as _ described in Section 
15.10.20. 


XDELTA confirms that the base register is set by displaying the 
expression deposited in the base register. 


15.10.15 Proceeding from Breakpoints 
Syntax 
7P RET 


Type a semicolon (;) followed by the letter P and return ( ft) ). 
XDELTA continues executing at the current PC. 


15.10.16 Loading PC and Continuing 


Syntax 
address expression;G RET 
Type an address, a semicolon, and G and then press) return. XDELTA 


loads the address into PC and continues executing at the new PC. 
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15.10.17 Display Mode Control 


Syntax 
[B Byte width 
[W Word width 
[L Longword width 


7 ASCII display (using current width) 


Type a left square bracket ([) followed by one of the letters B, W, or 
L to change the current display width to byte, word, or longword 
respectively. The default value is longword. The setting remains in 
effect until another display mode control command is given. For 
example, the following command displays the least significant byte 
contained at the specified address and deposits the new value to that 
byte only. 


address expression [B/ old value new value RET 


You can display contents of memory locations in ASCII characters’ by 
typing an address expression followed by a double quotation mark ("). 


address expression" old_value_in ASCII 
A line feed ( ) command displays the next location in ASCII. 
The display mode remains set to ASCII until the next slash (/) 


command. At this point, the display mode reverts to hexadecimal. 
Width remains unchanged. 


15.10.18 The Execute String Command 
Syntax 

address expression;E RET 
Type an address expression followed by a Semicolon, the letter E, and 
(RET) ‘ This command executes the ASCII commands’ found at_ the 
specified address expression. If you terminate the ASCII commands 
with a semicolon followed by the letter P, XDELTA will proceed with 


program execution. If you terminate the string with null (1 byte of 
0), XDELTA waits for a new command. 


To create command strings, open the address of the start of the string 
and deposit ASCII text as follows: 


address/fold-contents 'XDELTA-command' RET 
You can use any XDELTA command, including f& , , and a . 
To terminate the string with a null, follow the above command with: 
./old-contents 0 RET 
You can deposit command strings into nonpaged system patch space. To 
determine the size of patch space and its starting address, locate the 
symbol PATSA_NONPGD in the system map file (SYSSSYSTEM:SYS.MAP). This 
symbol contains a descriptor of the address and size of patch space 
remaining in the system, as shown below: 


PATSA_NONPGD: : 


. LONG size-in-bytes 
» LONG patch-space~start-address 
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You can also preassemble command strings with your experimental 
driver. Locate the addresses of these strings as you would any other 
address within your driver. 


15.10.19 Setting Complex Breakpoints 
Syntax 
address-expression,n,display address-expression,command_string_address;B 


Type an address expression, followed by a comma, a_e Single digit 
between 2 and 8, another address expression, and the address of a 
command string. The first address is the breakpoint address; the 
digit equals the breakpoint number. XDELTA shows the contents of the 
display address in the current display mode when the breakpoint is 
reached. The command string address specified in the last command 
parameter executes after automatic display. 


15.10.20 XDELTA Stored Commands 


XDELTA contains two predefined command strings whose addresses are 
contained in base registers XE and XF. You can use these commands 
during general system debugging aS well as driver debugging; they 
perform the following functions: 


XE Use the value of base register X0 as a page frame number 
and display the PFN data base for that page. 


XF Set base register X0 to the value (PFN) in RO and perform 
the same function as XE 


You must initialize the stored commands to set the relocation 
registers they use (X6-XD). Issue the following commands: 


Xk ee RET 
Xo te RET 
Now you can use the stored commands to obtain the following 


information about a page frame number: 
e Specified physical page number (PFN) 
e PFN state 
e PFN type 
e PFN reference count 
e@ PFN backward link/working set list index 
e PFN forward link/share count 
e Page table entry (PTE) pointer to PFN 
e PFN backing store address 


e Virtual block number in process Swap image 
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15.10.21 Stored Base Registers 

XDELTA defines two base registers useful in system debugging: X4 and 
XS. Base register X4 corresponds to the global symbol SCHSGL CURPCB. 
This symbol contains the address of the current process's’ software 
process control block (PCB). Base register X5 corresponds to the 


global symbol SCHSGL PCBVEC, which contains the starting address of 
the list of PCB slots. 


15.11 DELTA 
DELTA is a debugging tool that can be linked with a user program to 
examine that program's execution. To link and run DELTA, issue the 
following commands: 

$ LINK program-name 

$ QVEFINE LUBRSNE BUG SYS#LIBRARY? DELTA 

$ RUN/DER program-name 


DELTA accepts all the XDELTA commands, plus two additional commands 
described in the following sections. 


15.11.1 The EXIT Command 
syntax 
EXIT 


Typing EXIT causes DELTA to return control to the command interpreter. 


15.11.2 Examining and Modifying Locations in Process Space 
syntax 

process id:address expression/old contents 
DELTA displays the current contents at’ the specified address 
expression within the specified process. The modify flag controls the 
ability to modify locations opened by this command. To examine’ the 
flag, type: 

7M RET 
Modify access is inhibited by default (M=0). 


To open, examine and change a location, type the commands: 


13M RET 
process id:address expression/old contents new _contents (te) 


15.12 DEBUGGING TECHNIQUES 


The following sections discuss errors commonly made during debugging 
sessions and describe additional debugging techniques. 
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15.12.1 References to System Addresses 


References by drivers to system addresses within the executive must 
use general addressing (G”~) mode. For example, use 


JSB G“ INISBRK 


15.12.2 Opening Device Registers in XDELTA 


References to 16-bit device registers must be word instructions; 
references to 8-bit device registers must be byte instructions. These 
restrictions apply to the XDELTA EXAMINE command; therefore, be sure 
to set the correct mode control before examining device registers. 
For example, if the address of the device CSR is in R4, give’ the 
following command: 


R4/csr_ address [W/cosr contents 


15.12.3 Incorrect References to Device Registers 


A common driver error iS to access a nonexistent device register or to 
access the correct register with an instruction of incorrect word 
length. On the VAX-11l1 processor these references cause a _UNIBUS 
adapter error interrupt. Normally, the system logs the error and 
continues. When debugging a device driver, it is a good idea to catch 
this type of driver error as early as_ possible. Set an XDELTA 
breakpoint at the place in the system where it detected a UNIBUS 
adapter error interrupt. Follow the steps outlined below: 


e Consult the system map file. Read the value of EXESDW780_INT. 

e Enter XDELTA and set ae breakpoint at the address of 
EXESDW780_INT. when a UNIBUS adapter error interrupt occurs, 
XDELTA executes the breakpoint at EXESDW780_ INT. 


@e Examine the stack as follows: 


KE/current stack pointer/saved R2_ 
a = saved R3 
saved R4 
saved R5 
saved PC @ 
saved PSL 


In many cases, the Saved PC on the stack is the address of the 
instruction that caused the error. In other cases (for example, when 
the offending instruction is executed at IPL 31), the saved PC is not 
the address of this instruction but an address some number of 
instructions later, when the system actually services the interrupt. 


15.12.4 XDELTA and System Failures 


Driver bugs can cauSe the operating system to suspend activity in such 
a way that you cannot invoke XDELTA. In this case, the only recourse 
is to induce a system failure. Follow the procedure described in the 
VAX/VMS System Dump Analyzer Reference Manual; the system will signal 
a fatal bugcheck. 
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To gain control in XDELTA following a fatal bugcheck, stop in SYSBOOT 
while initializing the system and set the BUGREBOOT parameter to zero. 
The system will stop in XDELTA, thereby allowing you to examine the 
device unit control block and other driver data to determine the 
driver error. 


Another, more thorough, way to determine the cauSe of a system failure 
is to leave the BUGREBOOT parameter set to 1, allow the system to 
reboot, and then invoke the System Dump Analyzer (SDA) to examine’ the 
condition of the I/O data structures at the time of the fatal 
bugcheck. The VAX/VMS System Dump Analyzer Reference Manual provides 
detailed information on fatal bugcheck stack format and how SDA can 
help debug a device driver. 
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THE I/O DATA BASE 


The I/O data base is a collection of control blocks allocated in 


nonpaged system memory. This data base provides the following 
information: 


e I/0 request packets describing in-progress I/O requests 
e Device characteristics of each device type 

e Number and type of each device unit 

e Current activity on each device unit 

e External entry points to all device drivers 


e Entry points for controller and device unit initialization 
routines 


e Interrupt vector dispatch code 
e Addresses of device registers 
e UNIBUS adapter map register bit map and data path bit map 


Much of this I/O data base is created and used only by VAX/VMS 
routines. Other parts are the primary source of data for the device 
drivers. The sections that follow identify all I/O data base control 
blocks and describe their fields. Field descriptions are in the order 
in which they appear in the control blocks. Driver code must consider 
fields flagged with asterisks (*) as read-only fields. Fields marked 
by "spare" or "unused" are reserved for future use by DIGITAL unless 
otherwise specified. 


The data structures described in this appendix are defined in source 
modules SYSDEF.MDL and STARDEF.MDL. 


A.l1 I/O REQUEST PACKET (IRP) 


When a user process queues a valid I/O request by issuing a Queue 1/0 
Request or Queue I/O Request and Wait system service, the service 
(EXESQIO) creates an I/O request packet. This packet contains a 
description of the request and receives the status of the I/O 
processing as it proceeds. 


The fields of an I/O request packet are illustrated in Figure A-l_ and 
detailed in Table A-l. 
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Figure A-l I/0 Request Packet 


Field Name 


IRPS$L IOQFL 


IRPSL IOQBL 


IRPSW_SIZE* 


IRPSB_TYPE* 


IRP$B_RMOD* 


IRP$L PID* 


IRPSL AST* 


IRPSL ASTPRM 
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Table A-1l 


Contents of an I/O Request Packet 


Contents 
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I/O queue forward link. EXESINSERTIRP reads and 
writes this field when the routine inserts I/O 
packets into an I/O request packet wait queue, 
IOCSREQCOM reads and writes this field when the 
routine dequeues I/O packets from an I/O request 
packet wait queue in order to send the packet to 
a device driver. 


I/O queue backward link. EXESINSERTIRP and 
IOCSREQCOM read and write these fields. 


Size of the I/O request packet. EXESOIO writes 
the symbolic constant, IRPSC_LENGTH, into this 
field when the routine allocates and fills an 
I/O packet, 


Type of control block. EXESQIO writes’ the 
symbolic constant DYNSC_IRP into this field when 
the routine allocates and fills an I/O packet. 


Access mode of the process at the time of the 
I/O request. EXESQIO obtains the processor 
access mode from the PSL and writes the value 
into this field. 


Process identification of the process that 
issued the I/O request. EXESOIO obtains the 
process identification from the process’ control 
block and writes the value into this field. 


Address of the AST routine specified by the user 
in the I/O request. If the process specifies an 
AST routine address in the QIO call, EXESQIO 
writes the address in this field. 


During I/O postprocessing, the kernel mode AST 
routine queues a user mode AST to the requesting 
process if this field contains the address of an 
AST routine. 


Address of a parameter to be sent as an argument 
to the AST routine specified by the user in the 
I/O request. If the process specifies an AST 
routine and a parameter to that AST routine in 
the QIO call, EXESOQIO writes the parameter in 
this field. 


During I/O postprocessing, the kernel mode AST 
routine queues a user mode AST if the IRPSL AST 
field contains an address, and passes the value 
in IRPSL_ASTPRM to the AST routine as an 
argument. 


(continued on next page) 
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Table A-1 (Cont.) 
Contents of an I/O Request Packet 
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Field Name Contents 
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IRPSL WIND Address of a window block describing the _ file 
being accessed in an I/O request. EXESQIO 
writes this field if the I/O request refers to a 
file-structured device. The ACP reads’ this 


field. 


When a process gains access to a file on a 
file-structured device or creates a logical link 
between a file and a process I/O channel, the 
device ACP creates a window control block (WCB) 
that describes the virtual-to-logical mapping of 
the file data on the disk. EXESQIO stores the 
address of this WCB in the IRPSL WIND field. 
IRPSL UCB* Address of the unit control block for the device 
7 assigned to the process I/O channel. EXESOQIO 
copies this value from the channel control 
block. 

IRPSW_FUNC I/O function code that identifies the function 
to be performed for the I/O request. The I/0 
request call specifies an I/0 function code; 
EXESQIO and driver FDT routines map the code 
value to its most basic level (virtual —> 


logical —™ physical) and copy the reduced value 
into this field. 


Based on this function code, EXESOIO calls FDT 
action routines to preprocess an I/O request. 
Six bits of the function code describe the basic 


function. The remaining 10 bits modify the 
function. 

IRPSB_EFN* Event flag number and group specified in the I/0 
request. If the I/O request call does not 
specify an event flag number, EXESQIO uses event 
flag O by default. EXESQIO writes this field. 
The I/O postprocessing routine calls SCHSPOSTEF 
to set this event flag when the I/0 operation is 
complete. 

IRPSB PRI* Base priority of the process when the I/0 
7 request was issued. EXESQIO obtains a value for 
this field from the process’ control block. 
EXESINSERTIRP reads this field to insert an I/O 
request packet into a = priority-ordered I/O 
request packet wait queue. 
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Table A-1 (Cont.) 
Contents of an I/O Request Packet 


Field Name Contents 
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IRP$L IOSB Virtual address of the process I/O status’ block 
that receives the final status of the I/O 
request at I/O completion. EXESQIO writes a 
value into this field if the I/O request call 
specifies an IOSB address. The I/O 
postprocessing kernel mode AST routine writes 
two longwords of I/O status into the IOSB- block 
after the I/O operation is complete. 


When an FDT routine aborts an I/O request’ by 
calling EXESABORTIO, EXESABORTIO zeroes” the 
IRPSL IOSB field so that I/O postprocessing does 
not write status into the block. 


IRPSW_CHAN* Index number of the process I/O channel for the 
request. EXESOIO writes this field. 


IRPSW_STS Status of the I/O request. EXESQIO initializes 
this field to 0. EXESQIO, FDT routines, and 
driver fork processes modify this field 
according to the current status of the I/0 


request. I/0 postprocessing reads this field to 
determine what sort of postprocessing is 


necessary (for example, deallocate system 
buffers and adjust quota usage). 


Bits in the IRP$W STS field describe the type of 
I/O function, as follows: 


IRPSV BUFIO Buffered I/O function 

IRPSV_ FUNC Read function 

IRPSV_PAGIO Paging I/O function 

IRPSV COMPLX Complex buffered I/0 
= function 


IRPSV_VIRTUAL Virtual I/O function 
IRPSV CHAINED Chained buffered I/0 
-_ function 

IRPSV_SWAPIO Swapping I/0 funtion 

IRPSV DIAGBUF Diagnostic buffer is present 

IRP$V_ PHYSIO Physical I/O function 

IRPSV_TERMIO Terminal I/0 (for priority 
increment calculation) 


IRPSV MBXIO Mailbox I/O function 
IRPSV_EXTEND An extended IRP is linked to 
this IRP 


IRP$V_FILACP File ACP I/O 





ener 


(continued on next page) 
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Table A-1 (Cont.) 
Contents of an I/O Request Packet 
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Field Name Contents 
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IRPSL SVAPTE For a direct I/0 operation, specifies the 
virtual address of the first page table entry 
(PTE) of the I/O transfer buffer. FDT routines 
that lock pages in memory for a direct I/0 
transfer write the PTE address in this field. 


For a buffered I/0 operation, specifies the 
address of the buffer in system address space. 
FDT routines that allocate system buffers for a 
buffered I/O transfer write this field. 


IOCSINITIATE copies the field into the device 
unit control block field UCBSL_SVAPTE before 
transferring control to a device driver start 
I/O routine. 


IRPSW_BOFF Byte offset in first page of a direct I/O 
transfer. FDT routines calculate this offset 


and write the field. 


For buffered I/O operations, FDT routines must 
write the number of bytes to be charged to the 
process in this field because these bytes are 
being used for a system buffer. 


IOCSINITIATE copies the field into the device 


unit control block field UCBSW_BOFF before 
calling a device driver start I/O routine. 


1/0 postprocessing uses IRPSW_BOFF in 
conjunction with IRPSW _BCNT and IRPSL SVAPTE to 
unlock pages locked for direct 1/0. For 


buffered I/0, I/O postprocessing adds the value 
of IRPSW BOFF to the process byte count quota. 


IRPSW_BCNT Byte count of I/0 transfer. FDT routines 
calculate the count value and write the field. 
IOCSINITIATE copies the field into the device 
unit control block field UCBSW BCNT before 
calling a device driver start I/O routine. 


For a buffered 1/0 read function, I/O 


postprocessing uses IRPSW BCNT to determine how 
many bytes of data to write to the user's 


buffer. 
IRPSL_IOST1 First I/O status longword. ITOCSREQCOM and 
(also called EXESFINISHIO(C) write the contents of RO 
IRPSL MEDIA) into this field. The I/O postprocessing routine 


copies the contents of this field into the user 
I/O status block. 


EXESZEROPARM copies a 0 and EXESONEPARM copies 
Pl into this field. This field is a good place 
to put a Queue I/O Request argument (Pl through 
P46) or a computed value. 
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Table A-1l (Cont.) 


Contents of an I/O Request Packet 


Field Name 


IRPSL_ IOST2 
(also called 
IRPSL MEDIA+4 
or IRPS$B_CARCON) 


IRPSW_ABCNT 


IRPSW_OBCNT 


IRPSL_SEGVBN 


IRPSL DIAGBUF* 


IRP$L_SEQNUM* 


IRPSL_ EXTEND 





Contents 


Second I/O status longword. IOCSREQCOM and 
EXESFINISHIO(C) write the contents of R1 into 
this field. The I/0 postprocessing routine 
copies the contents of this field into the user 
I/O status block. 


IRP$B CARCON contains carriage control 
instructions to the driver. EXESREAD and 
EXESWRITE copy the contents of P4 of the user's 
T/O request into this field. 


Accumulated bytes transferred in a virtual I/0 


transfer. Read and written by IOCSIOPOST after 
a partial virtual transfer. 


Original transfer byte count in a virtual I/0 
transfer. Read by IOCSIOPOST to determine 
whether a virtual transfer iS complete, or 
whether another I/O request is necessary to 
transfer the remaining bytes. 


Virtual block number of the current segment of a 


virtual I/O transfer. Written by IOCSIOPOST 
after a partial virtual transfer. 


Address of a diagnostic buffer in system address 
space. If the I/O request call specifies this 
address, and if a diagnostic buffer length is 
specified in the driver dispatch table, and if 
the process has diagnostic privilege, EXESOIO 
copies the buffer address into this field. 


EXESQIO allocates a diagnostic buffer in system 
address space to be filled by IOCSDIAGBUFILL 
during I/O processing. During 1/0 
postprocessing, the kernel tnode AST routine 
copies diagnostic data from the system buffer 
into the process diagnostic buffer. 


I/O transaction sequence number. If an error is 


logged for the request, this field contains the 
universal error log sequence number. 


Address of the I/O request packet extension 
linked to this packet. FDT routines write an 
extension address to this field when a device 
requireS more context than the I/0 request 
packet can accommodate. This field is read _ by 
IOCSPOST. IRPSV EXTEND in IRPSW STS is set if 
this extension address is used. a 
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Table A-1 (Cont.) 
Contents of an I/O Request Packet 
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Field Name Contents 
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IRPSL_ARB Address of the access rights block. This’ block 
is located in the process’ control block and 
contains the process privilege mask and UIC, 


which are set up as follows: 





ARBSQ_ PRIV Quadword containing process 
privilege mask 

SPARESL Unused longword 

ARBSL_UIC Longword containing process 
UIC 


A.2 DEVICE DATA BLOCK (DDB) 


The device data block is a variable-length block that identifies’ the 
generic device/controller name and driver name for a set of devices 
attached to a Single controller. The driver loading procedure creates 
a device data block for each controller during autoconfiguration at 
system startup and dynamically creates additional device data blocks 
for new controllers as they are added to the system using SYSGEN 
CONNECT commands. The procedure initializes all fields in the device 
data block. VAX/VMS routines and device drivers refer to the device 
data block. 


Fields of the device data block are illustrated in Figure A-2 and 
described in Table A-2. 
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DDB$T_NAME (up to 15 characters) * 


, DDB$T_DRVNAME (up to 15 characters) * 
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Figure A-2 Device Data Block 


Field Name 


DDBS$L_LINK* 


DDBSL_UCB* 


DDBSW_SIZE* 


DDBSB_TYPE* 


DDB$L_DDT 


DDB$L_ACPD 


DDB$T_NAME* 


DDB$T_DRVNAME* 
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Table A-2 
Contents of Device Data Block 


Contents 


1.0 PT mh 


Address of the next DDB. A zero indicates that 
this is the last DDB in the DDB chain. 


Address of the unit control block for the first 
unit attached to the controller. 


Size of the DDB. 


Type of control block. The driver loading 


procedure writes the constant DYNSC DDB into 
this field when the procedure creates the DDB. 


Address of the driver dispatch table. VAX/VMS 
can transfer control to a device driver only 
through addresses listed in the DDT, the CRB, 
and the UCB fork block. The driver prologue 
table of every device driver must specify a 
value for this field. 


Name of the default ACP for the controller. Tf 
the devices on the controller are 
file-structured devices, this field contains the 
first four letters of the name of an ACP that 
controls access to the devices, The driver 
prologue table specifies a value for this field 
if it is applicable. 


Generic name of the devices attached to. the 
controller. The first byte of this field is the 
number of characters in the generic name. The 
remainder of the field consists of a string of 
up to 15 characters in length that, suffixed by 
a device unit number, identifies devices on the 
controller. 


Name of the device driver for the controller. 
The first byte of this field is the number of 
characters in the driver name. The remainder of 
the field contains a string of up to 15 
Characters in length taken from the driver 
prologue table in the driver. 
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A.3 UNIT CONTROL BLOCK (UCB) 


The unit control block is a variable-length block that describes a 
Single device unit. Each device unit on the system has its own unit 
control block. The block describes or provides pointers to the device 
type, controller, driver, device status, and current I/O activity. 


During autoconfiguration, the driver loading procedure creates’ one 
unit control block for each DIGITAL-supported device unit in the 
system configuration. A privileged system uSer can request the driver 
loading procedure to create unit control blocks for additional devices 
with the CONNECT command to SYSGEN as described in Chapter 14. The 
procedure creates unit control blocks of the length specified in the 
driver prologue table of the device's driver. The driver uses’ UCB 
Storage located beyond the standard UCB fields for device-specific 
data and temporary driver storage. 


The driver loading procedure initializes some static unit control 


block fields when it creates the block. VAX/VMS and device drivers 
can read and modify all nonstatic fields of the unit control block. 


The fields of the unit control block that are present for all devices 


are illustrated in Figure A-3 and described in Table A-3, on pages 
A-10 and A-ll. 
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UCB$B_FIPL* UCB$B_TYPE* UCB$W_SIZE* 


UCB$W_VPROT* 


UCBS$W_CHARGE 


UCB$L_FOFL * 


UCB$L_FQBL * 


CAD e 


UCBSL_FPC 
UCB$L_FR3 _ 
UCB$L_FR4 

UCB$w_BUFQUO 
UCB$L_OWNUIC* 
UCB$L_CRB* 
UCB$L_DDB* 
UCB$L_PID* 
UCB$L_LINK * 


UCB$L_VCB* 


UCB$L_DEVCHAR 


UCB$L_DEVDEPEND 


UCB$L_IOQFL 





UCB$L_IOQBL 


UCBSW_UNIT* 


UCB$L_IRP 


UCB$B_AMOD* UCBS$B_DIPL* UCBSW_ REFC* 


UCB$W_DEVSTS 


UCBSW_BCNT 


UCBSW_ERRCNT 


Figure A-3 


UCB$L_AMB* 

UCB$W_STS 
UCB$L_DUETIM* 
UCBSL_OPCNT* 
UCB$L_SVPN* 
UCB$L_SVAPTE* 


UCB$W_ BOF F 


UCB$B_ERTMAX | UCB$B_ERTCNT 


Unit Control Block 
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Contents of Unit Control Block 
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UCBSL_ FQFL* Fork queue forward link. The link points to the 
next entry in the fork queue. EXESIOFORK and 
VAX/VMS resource management routines write this 
field. The queue contains addresses of UCBs 
that contain driver fork process’ context of 
drivers waiting to continue I/O processing. 


UCBSL_FQBL* Fork queue backward link. The link points’ to 
the previous entry in the fork queue. 
EXESIOFORK and VAX/VMS resource management 
routines write this field. 


UCBSW SIZE* Size of the UCB. The driver prologue table of 
= every driver must specify a value for this 
field. The driver loading procedure uses_ the 
value to allocate space for a UCB and stores the 
value in each UCB created. Extra space beyond 
the standard bytes in a UCB (UCBSK LENGTH) is 
for device-specific data and temporary storage. 


UCBSB_ TYPE* Type of the control block. The driver loading 


procedure writes the constant DYNSC_UCB into 
this field when the procedure creates the UCB. 


UCBSB_ FIPL* Fork interrupt priority level (IPL) at which the 

: driver of the device usually executes. The 
driver prologue table of every driver must 
specify a value for this field. The driver 
loading procedure writes the value in the UCB 
when the procedure creates the UCB. 


VAX/VMS creates a driver fork process that gains 
control in a driver start I/O routine at this 
IPL. When the driver creates a fork process 
after an interrupt, VAX/VMS' inserts the fork 
block into a fork queue based on this’ IPL. A 
VAX/VMS fork dispatcher executing at UCBSB FIPL 
dequeues the fork block and restores control to 
the suspended driver fork process. 


All devices that are attached to one UNIBUS 
adapter and actively compete for shared UNIBUS 
adapter resources and/or a controller data 
channel must specify the same value for the fork 
IPL field. 


UCBSL_FPC Fork process driver PC address. When a VAX/VMS 
routine saves driver fork context in order to 
suspend driver execution, the routine stores the 
address of the next driver instruction to be 
executed in this field. A VAX/VMS routine that 
reactivates a suspended driver transfers control 
to the saved PC address. 
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Field Name 


UCBSL_FPC 
(Cont. ) 


UCBSL_FR3 


UCBSL_FR4 


UCBSW_BUFQUO* 


UCBSW_VPROT* 


UCBSL_OWNUIC* 


UCBSL_CRB* 





THE I/O DATA BASE 


Table A-3 (Cont.) 
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Contents 
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VAX/VMS routines that suspend driver processing 
include EXESIOFORK, IOCSREQxCHANx IOCSREQMAPREG, 
ITOCSREQDATAP, and IOCSWFIKPCH. Routines that 
reactivate suspended drivers include 
IOCSRELCHAN, IOCSRELMAPREG, IOCSRELDATAP, 
EXESFORKDSPTH, and driver interrupt service 
routines. 


When a driver interrupt service routine 
determines that a device 1S expecting an 
interrupt, the routine restores control to the 
saved PC address in the device's UCB. 


Value of R3 at the time that a VAX/VMS”~ routine 
suspends a driver fork process. The value of R3 
is restored just before a suspended driver 
regains control. 


Value of R4 at the time that an operating system 
routine suspends a driver fork process. The 
value of R4 is restored just before a suspended 
driver regains control. 


Buffered I/O quota if this UCB’ represents a 
mailbox. 


Description of the volume protection if a volume 
is mounted on this device. . This field is 
written by the MOUNT command when a volume is 
mounted. It is read by EXESQIO to check logical 
or physical access to a device and by the 
device's ACP. It’ is written by the SET 
PROTECTION/DEVICE command. 


User identification code of volume owner. This 
field is written by the MOUNT command when a 
volume is mounted. It is read by EXESQIO to 
check logical or physical access to a device and 
by the device's ACP. It is also written by the 
SET PROTECTION/DEVICE command. 


Address of the primary channel request’ block 
associated with the device. The driver loading 
procedure writes this field after it creates the 
associated CRB. Driver fork processes read this 
field to gain access to device registers. 
VAX/VMS routines use UCBSL_ CRB to _ locate 
interrupt dispatching code and initialization 
routine addresses. 
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Address of the device data block associated with 
the device. The driver loading procedure writes 
this field when the procedure creates the 
associated UCB. VAX/VMS routines generally read 
the DDB field in order to locate device driver 
entry points, the address of a driver function 
decision table, or the ACP associated with a 
given device. 


UCBSL_DDB* 


Process identification code of the process”) that 
has allocated the device. Written by’ the 
device's ACP. 


UCBS$L_PID* 


UCBSL_LINK* Address of the next UCB in the chain of UCBs 
attached to a single controller and associated 
with a device data block. The driver loading 
procedure writes this field when the procedure 
adds the next UCB. Any VAX/VMS-” routines”) that 
examine the status of all devices on the system 
read this field. Such routines include 
EXESTIMEOUT, IOCSSEARCHDEV, and power failure 
recovery routines. 

UCBSL_ VCB* Address of the volume control block (VCB) that 
describes the volume mounted on the device. 
This field is written by the device's ACP and 


read by EXESQIOACPPKT and ACPs. 


Device characteristics bits. The driver 
prologue table of every driver should specify 
symbolic constant values (defined by the SDEVDEF 
macro) for this field. The driver loading 
procedure writes the field when the procedure 
creates the UCB. The Queue I/O Request system 
service reads the field to determine whether a 
device is spooled, file-structured, shared, has 
a volume mounted, and so on. 


UCBSL_DEVCHAR 


The system defines the following device 
characteristics: 


DEVSV_REC Record-oriented device 
DEVSV CCL Carriage control device 
DEVSV TRM Terminal device 
DEVSV DIR  Directory-structured device 
DEVSV SDI Single directory-structured 
ve device 
DEVSV SOD Sequential block-oriented 
~ device (e.g., magtape) 
DEVSV SPL Device is being spooled 
DEVSV NET Network device 
DEVSV_FOD  Files-oriented device (e.g., 
disk and magtape) 


(continued on next page) 
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UCBSL_DEVCHAR 
(Cont. ) 


UCB$B_DEVCLASS 
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DEVSV SHR Shareable device (used by more 
a than one program 
Simultaneously) 
DEVSV GEN Generic device 
DEVSV AVL Device is available for use 
DEVSV MNT Device is mounted 
DEVSV MBX Mailbox device 
DEVSV DMT Device is marked for dismount 
DEVSV ELG  Error-logging is enabled on 
. device 
DEVSV ALL Device is allocated 
DEVSV FOR Device is mounted foreign 
7 (i.e., non-file-structured) 
DEVSV SWL Device is software write-locked 
DEVSV_ IDV Device is capable of providing 
input 
DEVSV ODV Device is capable of providing 
a output 
DEVSV RND Device allows random access 
DEVSV_RTM Real time device 
DEVSV_RCK Read-checking is enabled on 


device 
DEVSV_WCK Write-checking is enabled on 
device 
Device class. The driver prologue table of 


every driver should specify a symbolic constant 
(defined by the SDCDEF macro) for this’ field. 
The driver loading procedure writes this field 
when the UCB is created. 


Drivers with set mode and device characteristics 
functions rewrite the value in this field with 
data supplied in an I/O request. 


The VAX/VMS system defines the following device 
classes: 


DCS DISK Disk device 

DCS_ TAPE Tape device 

DC$_SCOM Synchronous communications 
device 

DCS _CARD Card reader device 

DCS TERM Terminal device 

DCS LP Line printer device 

DCS REALTIME Real time device 

DC$_ MAILBOX Mailbox device 


Note that the definition of a device as realtime 
is somewhat subjective; it implies no special 
treatment by VAX/VMS. 
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UCBSB_DEVTYPE 





UCBSW_DEVBUFSIZ 


UCBSL_DEVDEPEND 


UCBSL_IOQFL* 
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Device type. The driver prologue table of every 
driver should specify a symbolic constant 
(defined by the SDTDEF macro) for this field. 
The driver loading procedure writes the field 
when the procedure creates the UCB. 


Drivers with set mode and device characteristics 
functions rewrite the value in this field with 
data supplied in an I/O request. 


Default buffer size. The driver prologue table 
can specify a value for this field if relevant. 
The driver loading procedure writes the field 
when the procedure creates the UCB. 


Drivers with set mode and device characteristics 
functions rewrite the value in this field with 
data supplied in an I/O request. This field is 
used by VAX-11 RMS for record I/O on 
non-file-oriented devices. 


Device-dependent data. Contains device- 
descriptive data that only the device driver can 
interpret. The driver prologue table can 


specify a value for this field. The driver 
loading procedure writes this field when the 
procedure creates the UCB. 


Drivers with set mode and device characteristics 
functions rewrite the value in this field with 
data supplied in an I/O request. 


I/O queue listhead forward link. The queue 
contains the addresses of I/O request packets 
waiting for processing on a device. 
EXESINSERTIRP inserts I/O request packets into 
the I/O request packet wait queue when a_ device 
is busy. IOCSREQCOM dequeues I/O request 
packets when the device is idle. 


The queue is a priority queue that has_ the 
highest priority packets at the front of the 


queue, Priority is determined by the base 
priority of the requesting process. Packets 
with the same priority are processed 


first-in/first-out. 


(continued on next page) 






Field Name 


UCBSL_IOQBL* 


UCBSW_UNIT* 


UCBSW_CHARGE* 


UCBSL_IRP 


UCBSW_REFC* 


UCBSB_ DIPL 


UCBSB_AMOD* 


UCBSL_AMB* 


UCBSW_STS 
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I/O queue listhead backward link. EXESINSERTIRP 
and IOCSREQCOM modify the I/0 request packet 
walt queue, 


Number of the physical device unit. Stored as a 
binary value. The driver loading procedure 
writes a value into this field when the UCB is 
created. Drivers for multiunit controllers read 
this field during unit initialization to 
identify a unit to the controller. 


Mailbox byte count quota charge, if the device 
is a mailbox. 


Address of the I/O request packet currently 
being processed on the device unit by a driver 
fork process. IOCSINITIATE writes an I/O 
request packet address into this field before 
the routine creates a driver fork process’ to 
handle an I/O request. A driver fork process 
obtains the address of the I/O request packet 
being processed from this field. 


The value contained in this field is valid if 
the UCBSV_BSY bit in UCBSW STS is set. 


Reference count of processes that currently have 
process I/O channels asSigned to the device. 
Incremented by the SASSIGN and SALLOC’ system 
services. Decremented by the SDASSGN- and 
SDALLOC system services. 


Device interrupt priority level at which the 
device requests hardware interrupts. The driver 
prologue table of every driver must specify a 
value for this field. The driver loading 
procedure writes the field when the procedure 
creates the UCB. 


Some device drivers raise IPL to this' value 
before reading or writing device registers. 


If the device unit is allocated, the access mode 


at which the allocation occurred. Written by 
the SALLOC and SDALLOC system services. 


Associated mailbox UCB pointer. This field is 
used for spooled devices and mailboxes. 


Device unit Status. Written by drivers, 
IOCSREQCOM, IOCSCANCELIO, IOCSINITIATE, 
IOCSWFIKPCH, IOCSWFIRLCH, EXESINSIOO, and 
EXESTIMEOUT. This field is read by drivers, the 
Queue I/O Request system service routines, 


ITOCSREQCOM, IOCSINITIATE, and EXESTIMEOUT. 





(continued on next page) 
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Field Name 





UCBSW_STS 
(Cont. ) 


UCBSW_DEVSTS 


UCBSL_DUETIM* 


UCBSL_OPCNT* 
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request packet in the I/O postprocessing queue. 
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This status word includes the following bits: 


UCBSV_TIM 
UCBSV_INT 
UCBSV_ERLOGIP 
UCBSV_CANCEL, 
UCBSV_ONLINE 
UCBSV_ POWER 


Timeout enabled 
Interrupts expected 

Error log in progress 
Cancel I/O on unit 

Device is online 

Power has failed while 
unit was busy 

Unit is timed out 
Receiver interrupt 

Unit is busy 

Device is being mounted 
Deallocate device at 
dismount 

Software believes volume 
is valid 

Unload volume at dismount 
Template unit control 
block from which other 
UCBs for this device are 
made. The SASSIGN system 
service checks this bit in 
the requested UCB and, if 
the bit is set, creates a 
UCB from the template. 
The new UCB is assigned 
instead. 


UCBSV_TIMOUT 


UCBSV_INTTYPE 
UCBSV_ BSY 


UCBSV_MOUNTING 
UCBSV_DEADMO 


UCBSV_VALID 


UCBSV_UNLOAD 
UCBSV_TEMPLATE 


Device-dependent status. Read and written by 
device drivers. 


Due time for I/0 completion. Stored as the 
low-order 32-bit absolute time (time in seconds 
Since the operating system was booted) at which 
the device will timeout. IOCSWFIKPCH- and 


IOCSWFIRLCH write this value when they suspend a 
driver to wait for an interrupt or timeout. 


EXESTIMEOUT examines this field in each UCB in 
the I/O data base once per second. If the 
timeout has occurred and timeouts are enabled 


for the device, EXESTIMEOUT calls a device 
timeout handler in the device driver. 


Count of operations completed on the device unit 
since VAX/VMS was’ booted. IOCSREQCOM writes 
this field every time the routine inserts an I/0 
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UCBSL_SVPN* 


UCBSL SVAPTE 


UCBSW_BOFF 


UCBSW_BCNT 
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Virtual address of a page table entry 
permanently allocated to the device by the 
driver loading procedure. This field is used 
for ECC error correction by disk drivers. 


If a driver prologue table specifies DPTSM SVP 
in the flags argument to the DPTAB macro, the 
driver loading procedure allocates a page of 
nonpaged system memory to the device. The 
procedure writes the virtual address of the page 
table entry into UCBSL SVPN when the procedure 
creates the UCB. 


For a direct I/O operation, the virtual address 
of the system page table entry (PTE) for the 
first page that is to be used in an TI/0 


transfer. For a buffered I/0 operation, the 
address of the system buffer used in the 
transfer. This field is used only in transfer 


operations. 


I/O postprocessing uses this field to deallocate 
the system buffer for a buffered I/O operation 
or to unlock pages locked for a direct I/0 
operation. 


IOCSINITIATE writes this field from IRPSL SVAPTE 
before calling a driver start I/O routine. 
Drivers read this value to compute the starting 
address of a transfer. 


For direct I/O operations, byte offset in first 
page of the transfer buffer. For buffered I/0 
operations, the number of bytes charged to a 
process for ae transfer. IOCSINITIATE copies 
this field from the I/O request packet. 


Drivers read the field in calculating the 
starting address of a DMA transfer. If only 
part of a DMA transfer succeeds, the driver 
adjusts the value in this field to be the byte 
offset in the first page of the data that was 
not transferred. 


Count of bytes in I/0 transfer. IOCSINITIATE 
copies this field from the I/O request packet. 
Drivers read this field to determine how many 
bytes to transfer in an I/O operation. 
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UCBSB_ERTCNT Error retry count of current I/O transfer. The 
driver sets this field to the maximum retry 
count each time it begins I/0 processing. 
Before each retry, the driver decreases the 
value in this’ field. If error-logging is 
occurring, IOCSREQCOM copies the value into the 
error message buffer. 


UCBSB_ERTMAX Maximum error retry count allowed for a_e single 
I/O transfer. The driver prologue table of some 
drivers specifies a value for this field. The 
driver loading procedure writes the field when 
the procedure creates the UCB. If error-logging 
is occurring, IOCSREQCOM copies the value into 
the error message buffer. 


UCBSW ERRCNT Number of errors that have occurred on_ the 
a device since the system was bootstrapped. The 
driver loading procedure initializes the field 
to O when the procedure creates the UCB. 
ERLSDEVICERR and ERLSDEVICTMO increment the 
value in the field and copy the value into an 
error message buffer. The DCL command SHOW 
DEVICE displays in its error count column the 
value contained in this field. 
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Unit control blocks are variable length depending on the type of 
device and whether the driver performs error-logging for the device. 
The error log UCB extension, if present, appears directly after the 
UCBSW_ERRCNT field of the standard UCB. 


The fields in the UCB error log extension are illustrated in Figure 
A-4 and described in Table A-4. 










UCB$B_CEX UCB$B_FEX | UCB$B_SPR | ucsse_stave 










UCBSL_EMB* 


UCBSW_FUNC | unused 


UCB$L_DPC 
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Figure A-~4 UCB Error Log Extension 


Field Name 


UCBSB_SLAVE* 


UCBSB_SPR 


UCBSB_FEX 


UCB$B_CEX 


UCBSL_EMB* 


UCBSW_FUNC 


UCBSL_DPC 


Another extension of the unit control block is the disk extension 


block. This 


follows the error log extension. A driver that Supports a disk must 
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Unit number of slave controller. 


Spare byte. This field is reserved for driver 


use, MBA drivers use this field to store a 
fixed offset to the MBA registers for the unit. 


Device-specific field. This field is’ reserved 
for driver use. 


Device-specific field. This field is’ reserved 
for driver uSe. 


Address of the error message buffer. If error 
logging is enabled and a device/controller error 
or timeout occurs, the driver calls ERLSDEVICERR 
or ERLSDEVICTMO to allocate an error message 
buffer and copy the buffer address into this 
field. IOCSREQCOM writes final device status, 
error counters, and I/O request status into’ the 
buffer specified by this field. 


I/O function modifiers. This field is read and 
written by drivers that log errors. 


Device-specific field. This field is’ reserved 
for driver use. 





extension is -present for all disk devices. 


allow space in the UCB for both the error:'log and disk extensions. 


Disk drivers use three bits in UCBSW_DEVSTS as follows: 


UCBSV_ECC 
UCBSV_DIAGBUF 
UCBSV_NOCNVRT 


ECC correction made 
Diagnostic buffer specifed 
No logical block number to 
media address conversion 


The fields are illustrated in Figure A-5 and described in Table A-5. 











UCBSW_OFFSET 


UCB$W_BCR 


UCB$L_MAXBLOCK 


UCB$W_DIRSEQ 


UCB$L_MEDIA 









ee 


UCB$W_EC2 UCBS$W_EC1 
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UCB$B_OFFRTC|UCB$B_OFFNDX 
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Figure A-5 UCB Disk Extension 


A-21 










THE I/O DATA BASE 


Table A-5 
UCB Disk Extension 





eee OE rate 





nn OY TER SS WSAANUE SIMI OAM apnea te eet a eins eens Reta ie tos ee boat Rete 2m st Aetna prennameepeemeduty: 


Field Name Contents 





SAO POF EEE ORT ST ee . Se ee ee cee Ce ee (a eee eee i ee enc ru cod 





atthe, ane aeons emmrmpthine raion Adee Ren 





Maximum number of logical blocks on a= random 
access device. This field is written by a disk 
driver during unit initialization and power 
recovery. 


UCBSL_ MAXBLOCK 


This field is a parameter of the disk device 
unit and must be reset to a standard value 
whenever the disk is started. 


UCBSW_DIRSEQ Directory sequence number. 


UCBSW_OFFSET Current offset register contents. 


UCBSL MEDIA Media address. 


UCBSW_EC1 ECC position register. This field records’ the 
Starting bit number of an error burst. Disk 
driver register dump routines copy the contents 
of this field into an error-logging or 
diagnostic buffer. 

The VAX/VMS correction routine IOCSAPPLYECC 
reads the contents of this field to locate the 
beginning of an error burst in a disk block. 

UCBSW_EC2 ECC position register. Records the exclusive OR 


correction pattern. Disk driver register dump 


routines copy the contents of this field into an 
error logging or diagnostic buffer. 


The VAX/VMS ECC correction routine IOCSAPPLYECC 
reads the contents of this field to correct disk 
data. 

UCBSB OFFNDX Current offset table index. When a disk driver 
i transfer ends in an error, the disk driver can 
retry the error a number of times with different 
offsets of the disk head from the centerline. 
This field is an index into a driver table of 
offset positions. 


Current offset retry count. This field records 
the number of times to try a particular offset 
setting in a disk transfer retry. 


UCBSB_OFFRTC 


UCBSW_BCR Byte count register. Some disk drivers use this 
field as an internal count of the number of 


bytes left to be transferred in an I/O request. 
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A.4 CHANNEL REQUEST BLOCK (CRB) 


The activity of each controller in a configuration is described in a 


channel request block. This control block contains pointers to the 
walt queue of drivers ready to gain access to a device through the 


controller. It also stores the entry points to the driver's interrupt 
service routines and device/controller initialization routines. 
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THE I/O DATA BASE 


The fields of the channel request block are illustrated in Figure A-64 
and described in Table A-4, 










Field Name 


CRBSL_WOQFL* 


CRBSL_ WQBL* 


CRBSW_SIZE* 


CRBSB_TYPE* 


unused 


unused 





CRB$L_WOBL 








CRB$B_TYPE* CRB$W_SIZE* 

















CRB$B_MASK CRB$W_REFC* 
CRB$L_LINK* 
CRB$L_INTD* —_ 


(nine longwords) 


CRB$L._INTD2* 
(nine jongwords} 








Figure A-6 Channel Request Block 
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Contents of Channel Request Block 


Contents 
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Controller data channel wait queue forward link. 


IOCSREQXCHANX and IOCSRELXCHAN insert and remove 
driver fork block addresses in this field. 


A channel wait queue contains addresses of 
driver fork blocks that record the context of 
Suspended drivers waiting to gain control of a 
controller data channel. If a channel is busy 
when a driver requests access to the channel, 
IOCSREOxXCHANx suspends the driver by saving the 
driver's context in the device's UCB fork block 
and inserting the fork block address in the 
channel wait queue. 


When a driver releases a channel because an _ I/O 
operation no longer needs the channel, 
IOCSRELXCHAN dequeues a driver’ fork block, 
allocates the channel to the driver, and 
reactivates the suspended driver fork process. 
If no drivers are awaiting the channel, 
IOCSRELXCHAN clears the channel busy bit. 


Controller channel wait queue backward link. 


IOCSREQXxCHANxX and IOCSRELXCHAN' read and write 
this field. 


Size of the CRB. The driver loading procedure 


writes this field when the procedure creates the 
CRB. 


Type of control block. The driver loading 
procedure writes the symbolic constant DYNSC_CRB 
into this field when the procedure creates’ the 
CRB. 
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CRBSW_REFC* Unit control block reference count. The driver 
loading procedure increases the value in this 
field each time the procedure creates a UCB for 


a device attached to the controller. 


Mask that describes the status of the 
controller. At present, only one bit, 
CRBSV BSY, is defined in this field. 
IOCSREQXCHANx reads the busy bit to determine 
whether the controller is free and sets this bit 
when it allocates the controller data channel to 
a driver. IOCSRELxCHAN clears the busy bit if 
no driver is waiting to acquire the channel. 


CRBSB_MASK* 


CRBSL_ LINK* Address of secondary CRB (for MASSBUS' devices 
only). This field is written by the driver 
loading procedure and read by IOCSREQSCHANx and 
IOCSRELSCHAN. 

CRBSL INTD* Interrupt transfer vector. The driver prologue 
7 table in every driver for an interrupting device 
specifies the address of a driver interrupt 
service routine. The driver loading procedure 


writes two instructions in this field: 


PUSHR #°M<RO,R1,R2,R3,R4,R5> 
JSB @#°driver isr address 


When a UNIBUS device generates an interrupt on 
the VAX-11 processor, a VAX/VMS UNIBUS adapter 
interrupt service routine transfers control to 
the JSB instruction. in a CRB. The UNIBUS 
adapter service routine determines the 
appropriate CRB address from the vector address 
of the device interrupt. 


The CRBSL_INTD field is nine longwords' long. 
Figure A-7 and Table A-7 describe the contents 
of the rest of block. 


CRBSL_INTD2* Second interrupt transfer vector for devices 


with multiple interrupt vectors. If the driver 
prologue table in a device driver specifies the 
address of a second driver interrupt service 
routine, the driver loading procedure creates a 


CRB long enough to contain two INTDx fields of 
nine longwords each. 


The first two longwords of the CRBSL_INTD2 field 
contain a PUSHR and JSB instruction’ to the 
second driver interrupt service routine. 
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There are aS many interrupt transfer vector blocks as there are device 
vectors. The number of device vectors is determined by the value 
specified in the /NUMVEC= qualifier to the SYSGEN CONNECT command. 


THE I/O DATA BASE 


The interrupt transfer vector blocks contained in the CRB_~ store 
executable code, driver entry points, and UNIBUS adapter information. 
The fields of the CRBS$L INTD block are illustrated in Figure A-7 and 
described in Table A-7.— 












VEC$Q_DISPATCH* 


VEC$L_IDB* 


VEC$L_INITIAL* 


VEC$B_DATAPATH| VEC$B_NUMREG | VEC$W_MAPREG 


VEC$L_ADP* 





VEC$L_UNITINIT* 


spare longword 


a eee 


spare longword 


Figure A-7 Contents of CRBSL_INTD 


Table A-7 
Fields of CRBSL_INTD 
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Contents 


Field Name 


VECSQ_DISPATCH* 































Contains the two interrupt dispatching 
instructions described above in the CRBSL INTD 
field. This field is written by the driver 
loading procedure. 

VECSL_IDB* Address of the interrupt data block for the 
controller. The driver loading procedure 
creates an IDB for each CRB and loads’ the 
address of the IDB in this’ field. Device 
drivers use the IDB address to obtain the 
virtual addresses of device registers. 


When a driver interrupt service routine gains 
control, the top of stack contains a pointer to 


the IDB. 


VECSL INITIAL* Address of the controller initialization 
= routine. If a device controller requires 
initialization at driver loading time and during 

recovery from a power failure, the driver 


specifies a value for this field in tthe driver 
prologue table. 


The driver loading procedure calls this routine 
each time the procedure loads the driver. The 
VAX/VMS powerfail recovery procedure also calls 
this routine to initialize a controller after a 
power failure. 
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Field Name Contents 

VECSW_MAPREG Number of the first UNIBUS adapter map register 
allocated to the driver that owns the controller 
data channel. IOCSREQMAPREG writes this’ field 
when the routine allocates a set of map 
registers to a driver fork process for a DMA 
transfer. IOCSRELMAPREG reads the field to 
deallocate a set of map registers. If the high 
bit (VECSV MAPLOCK) of this field is set, the 
map register set is permanently allocated. 


Device drivers read this field to calculate the 
starting address of a UNIBUS transfer. 


VECSB NUMREG Number of UNIBUS adapter map registers allocated 
~ to a driver. ITOCSREQMAPREG writes this field 
when the routine allocates ae set of map 
registers, IOCSRELMAPREG reads’ this field to 
deallocate a set of map registers. 


VECSB_DATAPATH The data path specifier. The bits that make up 
this field are used as follows: 


0 —™ 4 The number of the data path 
used in a DMA transfer. 
The routine IOCSREQDATAP 
sets this field when a 
buffered data path is 
allocated and clears’ the 
field when the data path is 
released. 


The routine IOCSLOADUBAMAP 
copies the contents of this 
field into the UNIBUS 
adapter map registers. 
These bits alSo serve as 
implicit input to the 
IOCSPURGDATAP routine. 


VECSV_LWAE Longword access enable 
(LWAE) bit. Drivers set 
this bit when they wish to 
limit the data path to 
longword-aligned random 
access mode. The routine 
IOCSLOADUBAMAP copies’ the 
value in this field to the 
UNIBUS adapter map 
registers. 


6 Reserved to DIGITAL. 
VECSV_PATHLOCK Buffered data path 
allocation Indicator. 


Drivers set this bit to 
specify that the buffered 
data path is permanently 
allocated. 
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VECSL_ADP* 
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Address of the UNIBUS adapter control block 
(ADP). The CONNECT command to SYSGEN- must 
specify the nexus number of the UNIBUS' adapter 
used by a controller. The driver loading 
procedure writes the address of the ADP for’ the 
specified UBA into the VECSL ADP field. 


IOCSREQMAPREG and IOCSRELMAPREG read and write 
fields in the ADP to allocate and deallocate 
UNIBUS adapter map registers. 

VECSL_UNITINIT* Address of the device unit initialization 
routine, it a device unit requires 
initialization at driver loading time and during 
recovery from a power failure, the driver 
specifies a value for this field in tthe driver 
prologue table. 


The driver loading procedure calls this’ routine 
for each device unit each time the procedure 
loads the driver. The VAX/VMS powerfail 
recovery procedure also calls this routine to 
initialize device units after a power failure. 


MASSBUS drivers that Support mixed device types 
must not use this field. Instead, they should 


specify unit initialization in the 
(DDTSL UNITINIT) unit initialization field of 
the driver dispatch table. Other drivers may 


use either field. 


A.5 INTERRUPT DATA BLOCK (IDB) 


The interrupt data block records controller characteristics. The 
driver loading procedure creates and initializes this block when the 
procedure creates a channel request block. The interrupt data block 
points to the physical controller by storing the virtual address of 
the control/status register. This register is the indirect pointer to 
all device unit registers. 


The fields of the interrupt data block are illustrated in Figure A-8 
and detailed in Table A-8. 
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IDBSL_OWNER 


SPARE | 19888_rvPe- 


a edadsiiitiienatcamenabadaial 


rca cae 


IDB$W_SIZE* 


IDBSW_UNITS 
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Figure A-~8 Interrupt Data Block 


Table A-8 
Contents of Interrupt Data Block 
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Field Name Contents 
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IDBSL_CSR* Address of the control/status register (CSR). 
The CONNECT command to SYSGEN must specify the 
address of a device's control/status register. 
The driver loading procedure writes the system 
virtual equivalent of this address into’ the 


IDBSL CSR field. 


Device drivers set and clear bits in device 
registers by referencing all device registers at 
fixed offsets from the CSR address. 


Address of the unit control block of the device 
that owns the controller data channel. 
IOCSREQXCHANX writes a UCB address into this 
field when the routine allocates a controller 
data channel to a driver. IOCSRELxCHAN confirms 
that the proper driver fork process is releasing 
a channel by comparing the driver's UCB with the 
UCB stored in the IDBSL_ OWNER field. If the UCB 
addresses are the same, IOCSRELxCHAN allocates 
the channel to a waiting driver by writing a new 
UCB address into the field. If no driver fork 
processes are waiting for the channel, 


TOCSRELXCHAN clears the field. 


IDBS$L_OWNER 


If the controller is a single-unit controller, 
the unit or controller initialization routine 
should write the UCB address of the_ single 
device into this field. 

IDBSW SIZE* Size of the IDB. The driver loading procedure 
es writes the constant IDBSK LENGTH into this field 
when the procedure creates the IDB. 

IDBSB_TYPE* Type of control block. The driver loading 
procedure writes the symbolic constant DYNSC IDB 
into this field when the procedure creates the 
IDB. 
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Contents 


Field Name 


IDB$W_UNITS* 
















Maximum number of unitsS connected to the 
controller. The maximum number of units is 
specified in the driver prologue table and may 
be overridden at driver loading time. 


















Address of the UNIBUS adapter control block 
(ADP). The CONNECT command to SYSGEN- must 
specify the nexus number of the UNIBUS adapter 
used by a device. The driver loading procedure 
writes the address of the ADP for the specified 
UNIBUS adapter into the IDPSL ADP field. 


IDBSL_ADP* 





List of UCB addresses. The size of this field 
is the maximum number of units supported by the 
controller, as defined in the driver prologue 
table, The maximum specified in the DPT can be 
overridden at driver load time. The driver 
loading procedure writes a UCB address into this 
field every time the routine creates a new UCB 
associated with the controller. 


IDB$L_UCBLST* 





A.6 ADAPTER CONTROL BLOCK (ADP) 


Each MASSBUS and UNIBUS adapter configured in the system is 
represented to VAX/VMS and driver routines’ by an adapter control 
block. The adapter control block stores adapter-specific static and 


dynamic data such as the adapter CSR address and map register wait 
queues. | 


The fields of the ADP are illustrated in Figure A-9 and described in 





ADP$L_CSR* 


ADP$L_LINK* 


ADP$B_NUMBER*| ADP$B_TYPE* ADP$W_SIZE* 
ADP$W_.ADPT YPE* ADP$W_TR* 


ADP$L_VECTOR* or ADP$L_CRB 


ADP$L_DPOFL 
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ADP$L_DPQBL 


ADP$L_MROFL 


ADP$L_MROBL 


ADP$W_MRBITMAP ADP$W_DPBITMAP 
(31: words) a 
[——— A 


DP$L_INTD* 
(512 I tongwords) = tiC®S 





Figure A-9 Adapter Control Block 
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ADPSL_CSR* Virtual address of the adapter configuration 
register. The CPU initialization sets this 


field. 


The configuration register marks the base of 
adapter register space, an area that contains 
data path registers, map registers, or any other 
registers appropriate to the implementation of 
the adapter. 


Address of next ADP. The CPU initialization 
routine writes this field. A value of 0 
indicates that this is the last ADP. 


ADPSL_LINK* 


Size of the ADP control block. The CPU 
initialization routine writes this field when 
the routine creates the ADP. For the UNIBUS 
adapter, this includes the UNIBUS interrupt 
service code and device vector table. 


ADPSW_SIZE* 


ADPSB_TYPE* Type of control block. The CPU initialization 
routine writes the symbolic constant DYNSC ADP 
into this field when the routine creates the 
ADP. 

ADPSB NUMBER* Number of this type of adapter (for example, the 
ce number for a third MASSBUS adapter is 2). The 
CPU initialization routine writes this field 
when the routine creates the ADP. 

ADPSW_TR* Nexus number of the adapter. The CPU 
initialization routine writes this field when 
the routine creates the ADP. The driver loading 
procedure compares the nexus number specified in 
a CONNECT command with this field of each ADP in 
the system to determine to which adapter a 
device is attached. 

ADPSW ADPTYPE* Type of adapter. The CPU initialization routine 
7 writes the symbolic constant ATS UBA into this 
field when the routine creates an ADP for a 
UNIBUS adapter. ATS MBA is the type code for a 
MASSBUS adapter. 7 
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ADPSL_VECTOR* Address of vector table. The table is 512 bytes 
of longword vectors, The CPU initialization 
routine allocates portions of nonpaged pool _ to 
create this table. Each longword in the vector 
table that corresponds to a vector in use 
contains the address of the controller's 
interrupt dispatcher (CRBSL INTD) plus 2. When 
the UNIBUS adapter interrupts on the behalf of 
its UNIBUS devices, the UNIBUS adapter’ service 
routine saves RO through R5, then determines the 
vector of the interrupting device, indexes’ into 
the vector table, and executes the instruction 
at CRBSL_INTD+2. 


Longwords in this table that correspond to 
unused vectors contain the address of an 
unexpected UNIBUS interrupt routine. 


ADPSL CRB Address of the MASSBUS adapter's channel request 
block. The CPU initialization routine sets this 
address when it creates the CRB and the adapter 
control block. 


ADPSL DPQFL* Data path wait queue forward link. IOCSREQDATAP 
~ and IOCSRELDATAP read and write this field. 
When a driver fork process requests a buffered 
data path and none is currently available, 
IOCSREQDATAP saves’ driver context in the 
device's UCB fork block, inserts the fork block 
address in the data path wait queue, and 
suspends the driver fork process. 


When another driver calls IOCSRELDATAP to 
release a buffered data path, the routine 
dequeues a UCB fork block address from the data 
path wait queue, allocates a data path to the 


driver, and reactivates that driver fork 
process, 
ADPSL_DPOQBL* Data path wait: queue backward link. 


IOCSREQDATAP and IOCSRELDATAP read and write 
this field. 


ADPSL_MRQFL* Map register wait queue forward link. 
IOCSREQMAPREG and IOCSRELMAPREG read and write 
these fields. When a driver fork process 


requests a set of map registers and the set is 
not currently available, IOCSREQMAPREG' saves 
driver fork context in the device's UCB fork 
block, inserts the fork block address in the map 
register wait queue, and suspends the driver 
fork process. 
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Field Name Contents 
ADPSL_MRQFL* When another driver calls IOCSRELMAPREG to 
(Cont. ) release a set of map registers, the routine 


dequeues a UCB fork block address from the map 
register wait queue, allocates the requested set 
of map registers to the driver, and reactivates 
that driver fork process, 


ADPSL_MRQBL* Map register wait queue backward link. 
ITOCSREQMAPREG and IOCSRELMAPREG read and write 
this field. 


ADPSW_DPBITMAP* Data path allocation bit map. IOCSREQDATAP and 
IOCSRELDATAP read and write this field. The CPU 
initialization routine sets the bit map to’ show 
as available all the buffered data paths 
supported by the UNIBUS adapter. The VAX-11 
UNIBUS adapter supports fifteen buffered data 
paths. 


The state of each of the available buffered data 
paths (whether in use or available) is recorded 
in the data path allocation bit map. One data 
path corresponds to each bit in the field. If a 
bit is clear, the related data path is currently 
allocated to a driver fork process. 


ADPSW_MRBITMAP*| Map register allocation bit map. The field is 


31 words long. IOCSREQMAPREG and IOCSRELMAPREG 
read and write this field. 


The state of each of the 496 map registers 
(whether in use or available) is stored in the 
map register bit map. One map register 
corresponds to each bit in the field. If a bit 
is clear, the related map register is currently 
allocated to a driver fork process. 


ADPSL INTD* Interrupt transfer vector. When a device 
~ attached to the UNIBUS adapter requests a 
hardware interrupt, the processor transfers 
control to the ADPSL INTD field of the UNIBUS 
adapter's control block. The field contains 
code that dispatches the interrupt to the proper 
driver interrupt service routine. The interrupt 
transfer vector is only used for UNIBUS adapters 
that directly generate interrupts. 
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A.7 DRIVER DISPATCH TABLE’ (DDT) 


Each device driver contains a driver dispatch table. The table lists 
entry points in the driver that various VAX/VMS routines call. An 


example is the entry point for the driver routine that starts an I/O 
operation on a device. 


THE I/O DATA BASE 


A device driver creates a driver dispatch table by invoking’ the 
VAX/VMS macro DDTAB. The fields in the driver dispatch table are 
illustrated in Figure A-10 and described in Table A-10. 


DDT$L_START 


DDT$L_UNSOLINT 


ODT$L_FDT 





DDT$L_CANCEL 
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DDT$L_REGDUMP 


ee ad 


DDT$W_ERRORBUF DDT$W_DIAGBUF 


DDT$L_UNITINIT 


DDT$L_ALTSTART 


Figure A-10 Driver Dispatch Table 


Table A-10 
Contents of Driver Dispatch Table 


Field Name Contents 
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DDTSL_ START Entry point to the driver start I/O routine. 
Every driver must specify this field with the 
value of the START argument in the DDTAB- macro 
invocation. 


When a device unit is idle and an I/O request is 
pending for that unit, IOCSINITIATE transfers 
control to the address contained in this field. 


DDTSL_UNSOLINT Entry point to the driver unsolicited interrupt 
service routine. The driver specifies this 
field with the value of the UNSOLIC argument in 
the DDTAB macro invocation. 


This field contains the address of a_e routine 
that analyzes unexpected interrupts from a 
device. The standard driver interrupt service 
routine, the address of which is stored in the 


CRB, determines whether an interrupt was 
solicited by a driver. If the interrupt is 


unsolicited, the service routine may call _ the 
unsolicited interrupt service routine. 


DDTSL_FDT Address of the driver's function decision table. 


Every driver muSt specify this field with the 
value of the FUNCTB argument in the DDTAB- macro 
invocation. | 
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DDTS$L_FDT 
(Cont. ) 


EXESQIO refers to the FDT to validate I/O 
function codes, decide which functions are 
buffered, and call FDT action routines 
associated with function codes, 


Entry point to the driver cancel I/0 routine, 
The driver specifies this field with the value 
of the CANCEL argument in the DDTAB-' macro 
invocation. 


DDTS$L_CANCEL 


Some devices require special clean-up processing 
when a process or a VAX/VMS routine cancels an 
I/O request before the I/O operation completes 
or when the last channel is deassigned. The 
SDASSGN, SDALLOC, and SCANCEL system. services 
cancel I/O requests. 

DDTSL_REGDUMP Entry point to the driver register dump routine. 
The driver specifies this field with the value 
of the REGDMP argument in the DDTAB macro 
invocation. 


IOCSDIAGBUFILL, ERLSDEVICERR, and ERLSDEVICTMO 
call the address contained in this field to 
write device register contents into a diagnostic 
or error-logging buffer. 

DDTSW_DIAGBUF Size of the diagnostic buffer. The driver 
specifes this field with the value of the DIAGBF 
argument in the DDTAB macro’ invocation. The 
value is the size in bytes of a diagnostic 
buffer for the device. 


When EXESQIO preprocesses an I/0 request, the 
routine allocates a system buffer of the size 
recorded in this field if the user process has 
diagnostic privileges, specifies a diagnostic 
buffer in the I/O request, and this field of the 
DDT contains a nonzero value. IOCSDIAGBUFILL 
fills the buffer after the I/O operation 
completes. 

DDTSW ERRORBUF Size of the error log buffer. The driver 
= specifies this field as the value of the ERLGBF 
argument in the DDTAB macro invocation. The 
value is the size in bytes of an error-logging 
buffer for the device. 


If error logging is enabled and an error occurs 
during an I/0 operation, the driver calls 
ERLSDEVICERR or ERLSDEVICTMO to allocate and 
write error-logging data into the error message 
buffer. IOCSINITIATE and IOCSREQCOM write 
values into the error message buffer if an error 
has occurred. 
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Field Name 








Contents 
DDTSL_UNITINIT Address of the device unit initialization 
routine, if one exists. Drivers for MASSBUS 
devices use this field rather than 


CRBSL_INTD+VECSL _UNITINIT. Drivers for UNIBUS 
devices may use either field. 


Address of the alternate start I/O routine. The 
VAX/VMS routine EXESALTOQUEPKT initiates the 
alternate start I/O routine at this address. 






DDTSL_ALTSTART 


A.8 DRIVER PROLOGUE TABLE (DPT) 


When loading a device driver and its data base into virtual memory, 
the driver loading procedure finds the basic description of the driver 
and its device in a driver prologue table. This table provides’ the 
length, name, adapter type, and loading and reloading specifications 
for the driver. 


A device driver creates a driver prologue table by invoking’ the 
VAX/VMS macros DPTAB and DPT STORE. The fields of the DPT are 
illustrated in Figure A-11 and described in Table A-ll. 
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DPT$L_FLINK* 


DPT$L_BLINK* 


DPT$B_REFC* DPT$B_TYPE DPT$W_SIZE 








DPT$W_UCBSIZE DPT$B_FLAGS |DPT$B_ADPTYPE 

DPTSW_REINITTAB _ DPT$W_IN TTAB 

DPT$W_MAXUNITS DPTSW_UNLOAD 
SPARE DPT$W_VERSION 


SPARE 
DPT$T_NAME 
(up to 15 characters) 


Figure A-ll Driver Prologue Table 





Field Name 
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DPTSL_FLINK* 


DPTSL_BLINK* 


DPTSW_SIZE 


DPT$B_ TYPE 


DPTSB_REFC* 


DPTSB_ADPTYPE 


DPTSB_FLAGS 
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Contents of Driver Prologue Table 
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Contents 


Forward link to the next DPT. The driver 
loading procedure writes this field. The 
procedure links all driver prologue tables in 
the system in a doubly linked list. 


Backward link to the previous DPT. The driver 
loading procedure writes this field. 


Size in bytes of the device driver. The DPTAB 
macro writes this field by subtracting the 
address of the beginning of the DPT from the 
address specified as the END argument in the 
invocation of the DPTAB macro. The driver 
loading procedure uses this value to determine 
the space needed in nonpaged system memory to 
load the driver. 


Type of control block. The DPTAB macro always 
writes the symbolic constant, DYNSC DPT, into 
this field. - 


Number of device data blocks that refer to this 
driver. The driver loading procedure increments 
the value in this field each time the procedure 
creates another DDB that points to the driver's 
DDT. 


Type of adapter used by devices driven by this 
driver. Every driver must specify the string 
"UBA" or "MBA" as value of the argument ADAPTER 
in the invocation of the DPTAB macro. The macro 
writes the value ATS UBA or ATS MBA in this 
field. 7 ~ 


Driver loader flags. The driver can specify any 


of a set of flags as the value of the argument 
FLAGS in the invocation of the DPTAB macro. The 


driver loading procedure modifies the loading 
and reloading algorithm followed based on_ the 


settings of these flags. 


Flags defined in the flag field include’ the 
following: 


DPTSM_SUBCNTRL Device is a subcontroller 
DPTSM SVP Device requires permanent 
system page; allocated 


during driver loading 


DPTSM_NOUNLOAD Driver cannot be reloaded 
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DPTSW_UCBSIZE Size in bytes of unit control blocks created for 
device units driven by this driver. Every 
driver must specify a value for this field as 
the value of the argument UCBSIZE in the 
invocation of the DPTAB macro. 


The driver loading procedure allocates blocks of 
nonpaged system memory of the specified size 
when creating UCBs for devices associated with 
the driver. 


DPTSW_INITTAB Offset to driver initialization table. Every 


driver must specify a list of control block 
fields and values to be written into the fields 


at the time that the driver loading procedure 
creates the control blocks. 


The driver invokes the VAX/VMS macro DPT STORE 
to specify these fields and their values. Every 
driver must specify the following fields: 


UCBSB FIPL Fork interrupt priority 
— level 

UCBSB DIPL Device interrupt priority 
- level 


Other commonly initialized fields are: 


UCBSL_DEVCHAR Device characteristics 
UCBSB_DEVCLASS Class of device 
UCBSB DEVTYPE Type of device 


UCBSW_DEVBUFSIZ Default buffer size 
UCBSL DEVDEPEND Device-dependent 


parameters 


DPTSW_REINITTAB Offset to driver reinitialization table. Every 
driver must specify a list of control block 


fields and values to be written into fields at 
the time that the driver loading procedure 
creates the control blocks or loads the driver. 


The driver invokes the VAX/VMS macro DPT STORE 

to specify these fields and their values. Every 

driver must specify the following field: 
DDBSL_DDT Driver dispatch table 


Other commonly initialized fields are: 





CRBSL INTD+4 Interrupt service routine 
CRBSL INTD2+4 Second interrupt service 
7 routine 
VECSL INITIAL Controller initialization 
7 routine 
VECSL_UNITINIT Unit initialization 
routine 
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DPTSW_UNLOAD Relative address of a driver action routine to 
be called when a driver is reloaded. The driver 
specifes this field with the value of the UNLOAD 


argument in the invocation of the macro DPTAB. 


If the driver requires special clean-up 
processing such as buffer or map register 
deallocation before the driver can be reloaded, 
the driver must specify this field. The driver 
loading procedure calls the driver unloading 
routine before reinitializing all device units 
associated with the driver. 


The DPTAB macro fills this field with the 
current version of VAX/VMS. This field is 
checked at driver load time for the correct 
value. 


DPTSW_VERSION 


DPTST NAME Name of the device driver. Field is 12 bytes in 
7 length. One byte records the length of the name 
string; the name string can be up to ll 
characters in length. Drivers specify this 
field as the value of the NAME argument in the 


invocation of the DPTAB macro. 


The driver loading procedure compares the name 
of a driver to be loaded with the values in this 
field in all DPTs already loaded into system 
memory. If the procedure finds a match, the 
procedure unloads the old driver and replaces it 
with the new driver. Otherwise, the procedure 


adds a new DPT to the DPT linked list and_ then 
loads the new driver. 





A.9 CHANNEL CONTROL BLOCK (CCB) 


When a process assigns an I/O channel to a device unit with the Assign 
I/O Channel system service, EXESASSIGN locates a free block among the 
process's preallocated channel control blocks. EXESASSIGN then writes 
a description of the device attached to the channel in the CCB. 


The fields of a channel control block are illustrated in Figure A-12 
and described in Table A-12. 
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Figure A-12 Channel Control Block 


THE I/O DATA BASE 


Table A-12 
Contents of Channel Control Block 


AS ANN RR 





Contents 


Field Name 


CCBSL_UCB* 





Address of the unit control block of the 
assigned device unit. EXESASSIGN writes a value 
into this field. EXESQIO reads this field to 
determine that the I/0 request specifies a 


process I/O channel assigned to a device and to 
obtain the device's UCB address, 










Address of window control block for a 


file-structured device assignment. This field 
is written by an ACP and read by EXESOIO. 










CCBSL_WIND* 


A file-structured device's ACP creates a window 
control block when a process accesses a file on 
a device asSigned to a process’7 channel. The 
window control block maps the virtual block 
numbers of the file to a series of physical 
locations on the device. 


CCBSB_STS* Channel status. 






CCBSB_AMOD* Access mode plus 1 of the process at the time of 
the channel assignment. EXESASSIGN writes the 


process access mode value into this field. 














CCBSwW_Ioc* Number of outstanding I/0 requests on_ the 
channel. EXESQIO increases this field when it 
begins to process an I/O request that’ specifies 
the channel. During I/O postprocessing, the 
kernel mode AST routine decrements this field. 
Some FDT routines and EXESDEASSIGN read this 
field. 

CCBSL_DIRP* Address of deaccess I/O request packet. A 
number of outstanding I/O requestS can be 
pending on the same process I/O channel at one 
time. If the process that owns the channel 
issues an I/O request to deaccess the device, 
EXESQIO holds the deaccess' request until all 
other outstanding I/O requests are processed. 





A.10 I/O REQUEST PACKET EXTENSION (IRPE) 


I/O request packet extensions hold additional I/O request information 
for devices that require more context than the standard I/O request 
packet can accommodate. IRP extensions are also used when more than 
one buffer (region) must be locked into memory for a direct I/0 
operation, or when a transfer requires a buffer that is larger’ than 
64K bytes. An IRPE provides space for two buffer regions, each with a 
32-bit byte count. 


FDT routines allocate IRPES by calling EXESALLOCIRP. Driver routines 
link: the IRP extension to the I/0 request packet by storing the 
extension's address in two fields within the packet: IRPSV_EXTEND in 


IRPSW STS and IRP$SL EXTEND. The FDT routine initializes the contents 
of the IRPE. Any fields within the extension not described in Table 


A-13 can store driver-dependent information. 


THE I/O DATA BASE 


If the IRP extension specifies additional buffer regions, the FDT 
routine must use those buffer locking routines that perform coroutine 
calls back to the driver if the locking procedure fails 


(EXESREADLOCKR, EXESWRITELOCKR, and EXESMODIFYLOCKR). If an error 
occurs during the locking procedure, the driver must unlock all 


previously locked regions and deallocate the I/0 request packet 
extension before returning to the buffer locking routine. 


IOCSIOPOST automatically unlocks the pages in region 1 (if defined) 


and region 2 (if defined) for all the IRP extensions linked to the 
packet being completed. IOCSIOPOST also deallocates all the IRPEs. 


The fields of the I/O request packet extension are illustrated in 
Figure A-13 and described in Table A-13. 
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Figure A-13 I/O Request Packet Extension 


THE I/O DATA BASE 


Table A-13 
Contents of the I/O Request Packet Extension 


Field Name Contents 


IRPESW_ SIZE Size of the I/O request packet extension. 
EXESALLOCIRP writes the constant IRPSC_LENGTH to 
this field. 


IRPESB_ TYPE Type of control block. EXESALLOCIRP writes’ the 
constant DYNSC_IRP to this field. 


IRPESW_STS IRP extension status field. Bits in the status 
field describe the following conditions: 


IRPESV_EXTEND Another IRPE is linked 
to this one 


IRPESL SVAPTE1 System virtual address of the page table entry 
mapping the start of region 1. FDT routines 
write this field. If the region is not defined, 
this field is zero. 


IRPESW_BOFF1 Byte offset of region 1. FDT routines wtite 
this field. 


IRPESL BCNT1 Size in bytes of region 1. FDT routines write 
i this field. 


IRPESL SVAPTE2 System virtual address of the page table entry 


mapping the start of region 2. Set by FDT 
routines. This field contains a value of zero 
if region 2 is not defined. 


IRPESW_BOFF2 Byte offset of region 2. This field is set by 
FDT routines. 


IRPESL BCNT2 Size in bytes of region 2. FDT routines’ write 
this field. 





APPENDIX B 


VAX/VMS MACROS INVOKED BY DRIVERS 


This appendix contains an alphabetical listing of macros that drivers 
e. Default values are provided where applicable. 


invok 


CASE 


DDTAB 


DPTAB 


SRC 
DISPLIST 


TYPE=W 
LIMIT=#0 
NMODE=S“ # 


DEVNAM 
START=0 
UNSOLIC=0 


FUNCTB 
CANCEL=0 
REGDMP=0 
DIAGBF=0 
ERLGBF=0 
UNITINIT=0 
ALTSTART=0 


END 
ADAPTER 
FLAGS=0 


UCBSIZE 
[UNLOAD] 


MAXUNITS=8 
NAME 


Generates a CASE instruction and CASE table 


Source of CASE index value 

List of deStinations for each case (destl, dest2, 
dest3) 

Data type (B, W, L) 

Lower limit of CASE value 

Address mode for number of table entries; the 
short literal default is good for up to 63 entries 


Generates a driver dispatch table named devnamSDDT 


Generic device name 

Address of start I/O routine 

Address of unsolicited interrupt service routine 
for MASSBUS drivers 

Address of function decision table 

Address of cancel I/O routine 

Address of error-logging register dump routine 
Length in bytes of diagnostic buffer 

Length in bytes of error logging buffer 

Device unit initialization routine 

Alternate Start I/O routine 


Generates a driver prologue table in PSECT 
$$$105 PROLOGUE 


Address of the end of the driver 

Type of adapter (UBA or MBA) 

Driver loading flags (DPTSM SVP and 
DPTSM NOUNLOAD) = 

Size in bytes of each device UCB 

Optional address of a routine to call if the 
driver is to be unloaded 

Maximum number of units that can be connected 
Driver name 


DPT STORE 


STR_ TYPE 


STR_OFF 
OPER 


EXP 

POS 

SIZE 
DSBINT 


[IPL] 


[DST] 


ENBINT 


[SRC] 


FORK 


FUNCTAB 


[ACTION] 


CODES 


IFNORD 
SIZ 
ADR 
DEST 


MODE=#0 


IFNOWRT 
o1Z 
ADR 
DEST 


MODE=#0 


VAX/VMS MACROS INVOKED BY DRIVERS 


Generates a table containing initialization values 
for fields in the I/O data hbase 


Type of control block (DDB, UCB, CRB, IDB); or 
table marker (INIT, REINIT, END) 

Offset into control block 

Type of initialization operation (B=byte, W=word, 
L=long, D=address relative to driver, V=hbit 
field); if an at sign (@) precedes the OPERATION, 
then the EXPRESSION argument is the address of the 
initialization data 

Initialization value to be stored in control block 
Bit position for OPERATION=V 

Field size for OPERATION=V 


Disables interrupts by raising IPL 


IPL value to be loaded into the IPL processor 
register PRS IPL (defaults to 31) 

Location for old IPL value (defaults to top of 
stack ) 


Enables interrupts by restoring a saved IPL 


Location in which an IPL is saved (defaults to top 
of stack) 


Calls EXESFORK to create a fork process 


Generates a function decision table consisting of 
two 64-bit entries of function codes, and n 96-bit 
entries of function codes and action routine 
addresses 


Address of an FDT routine to call for the function 
codes listed 
A list of I/O function codes 


Branches if a range of addresses is not readable 


Number of bytes in range 

Address of first byte in range 

Location to branch to if the range of addresses is 
not readable 

Access mode at which to probe (defaults to USER) 


Branches if a range of addresses is not writeable 


Number of bytes in range 

Address of first byte in range 

Location to branch to if the range of addresses is 
not writeable 

Access mode at which to probe (defaults to USER) 


ILFRD 


SIZ 
ADR 
DEST 


MODE=#0 


IOFORK 


LOADUBA 


PURDPR 


RELCHAN 


RELDPR 


RELMPR 


RELSCHAN 





REQDPR 


REQMPR 


REQPCHAN 


[PRI] 


REQSCHAN 


[PRI] 





VAX/VMS MACROS INVOKED BY DRIVERS 


Branches if a range of addresses is readable 


Number of bytes in range 

Address of first byte in range 

Location to branch to if the range of addresses is 
readable 

Access mode at which to probe (defaults to USER) 


Calls EXESIOFORK to create a device driver fork 
process | 


Calls IOCSLOADUBAMAP to load a preallocated set of 
UNIBUS adapter map registers 


Calls IOCSPURGDATAP to purge a data path 


Calls IOCSRELCHAN to release all controller data 
channels that are allocated by the driver 


Calls IOCSRELDATAP to release a preallocated 
UNIBUS adapter data path 


Calls IOCSRELMAPREG to release a preallocated set 
of UNIBUS adapter map registers 


Calls IOCSRELSCHAN to release all secondary 
controller data channels that are allocated by the 
driver 


after 


Calls IOCSREQDATAP to request a UNIBUS adapter 
data path 


Calls IOCSREQMAPREG to request a set of UNIBUS map 
registers 


Calls IOCSREQPCHANH or IOCSREQPCHANL to request a 
primary controller data channel 

Priority of request; if PRI=HIGH, calls 
IOCSREQPCHANH; otherwise calls IOCSREQPCHANL 
Calls IOCSREQSCHANH or IOCSREQSCHANL to request a 


secondary controller data channel 


Priority of request; if PRI=HIGH calls 
ITOCSREQSCHANH; otherwise calls IOCSREQSCHANL 


SAVIPL 


DST=- (SP) 


SETIPL 


[IPL] 


SOFTINT 


IPL 





EXCPT 


[TIME ] 


WFIRLCH 


EXCPT 


[TIME ] 


VAX/VMS MACROS INVOKED BY DRIVERS 


Saves the current IPL value as recorded in the 
processor register PRS IPL 


Location in which to save the 
(defaults to a new top of stack) 


current IPL 


Sets IPL to a new value 


New IPL value (defaults to 31) 


Initiates a software interrupt 


IPL value of the interrupt; loads IPL into the 
processor register PRS SIRR 


Calls an executive Subroutine to wait for an 
interrupt or a device timeout and keep. the 
controller data channel 


Relative address of a device timeout handling 
routine; writes the address into the two bytes 
following the call to the executive routine. 
Number of seconds to allow before a device timeout 
(defaults to 65536 seconds) 


Calls an executive subroutine to wait for an 
interrupt or a device timeout and release the 
controller data channel 


Relative address of a device timeout handling 
routine; writes the address into the two bytes 
following the call to the executive routine. 
Number of seconds to allow before a device timeout 
(defaults to 65536 seconds) 


APPENDIX C 


OPERATING SYSTEM ROUTINES 


This appendix describes the VAX/VMS operating system routines that are 
used by device drivers. The information given in this section follows 
the conventions listed below: 

e Fields used for both input and output are not specified. 


e Registers are assumed preserved unless otherwise specified. 


e IPL at execution refers to the interrupt priority level at 
which the routine executes, not the IPL at which it is called. 


COMSDELATTNAST in module COMDRVSUB 


Driver fork processes call this routine to deliver all the AST control 
blocks linked to the specified AST list. 


INPUT TO ROUTINE 


Registers Contents 

R4 Address of specified listhead 

R5 Address of the unit control block 
Fields Contents 


IPL at execution: caller's IPL 
This routine removes all AST blocks from the specified list and 


schedules an IPLS QUEUEAST level fork process to queue each AST to its 
process. 


OUTPUT FROM ROUTINE 


Registers Contents 
Fields Contents 
Specified listhead 0 


IPL at exit: caller's IPL 


OPERATING SYSTEM ROUTINES 


COMSDRVDEALMEM in module COMDRVSUB 


Drivers use this routine to deallocate system dynamic memory. 
COMSDRVDEALMEM can be called from any interrupt priority level. 


INPUT TO ROUTINE 


Registers Contents 

RO Address of the block to be deallocated 
Fields Contents 

IRPSW_SIZE Size of the block in bytes 


IPL at execution: caller's IPL and IPLS QUEUEAST 

If the block size is smaller than 24 bytes or the block is not 
properly aligned, a system bugcheck occurs. This routine also calls 
SCHSRAVAIL to mark the resource free. | 


IPL at exit: caller's IPL 


COMSFLUSHATTNS in module COMDRVSUB 


Driver FDT and fork routines call this routine to flush an attention 
AST list. Drivers use this routine during cancel I/O operations. 


INPUT TO ROUTINE 


Registers Contents 

R4 Address of the current PCB 

R5 Address of the UCB 

R6 Number of the assigned channel 

R7 Address of the AST control block listhead 
Fields Contents 

UCBSB_DIPL Device IPL 

PCBSL PID Process's ID 

PCBSW_ASTCNT ASTs remaining in quota 


IPL at execution: device IPL (UCBSB DIPL) 


COMSFLUSHATTNS locates all the control blocks whose channel number and 
process identification match those specified as input to the routine, 
removes them from the specified list and deallocates' them. This 
routine exits by returning to its caller. 


OPERATING SYSTEM ROUTINES 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SS$_NORMAL 

Rl Destroyed 

R2 Destroyed 

R7 Destroyed 

Fields Contents 

PCBSW_ASTCNT Number of ACBs flushed (added to previous 


contents) 
Specified listhead Updated 


IPL at exit: caller's IPC 


COMSPOST in module COMDRVSUB 


Drivers call this routine after they have completed all 
device-dependent I/0 postprocessing for an I/O request. This routine 
inserts the I/O request packet into the I/O postprocessing queue _ and 
returns to the driver fork process. COMSPOST operates independently 
of the device unit; it does not attempt to dequeue another packet nor 
does it change the busy status of the device. 


Drivers can use this routine to complete I/O request packets initiated 
by the routine EXESALTQUEPKT. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the I/O request packet 

R5 Address of the unit control block 

Fields Contents 

IRP$L_ MEDIA Data to be copied into the I/O status block 
IRPSL MEDIA+4 Data to be copied to the I/O status block 


IPL at execution: caller's IPL (driver fork level or above) 


This routine places the I/O request packet into the queue headed _ by 
IOCSGL_PSBL. 


OPERATING SYSTEM ROUTINES 


OUTPUT FROM ROUTINE 


Registers Contents 
RO Destroyed 
Rl Destroyed 
Fields Contents 
UCBSL_OPCNT Incremented by 1 


IPL at exit: caller's IPL 


COMSSETATTNAST in module COMDRVSUB 


Driver FDT routines call this routine to enable or disable attention 


ASTs, depending upon the contents of the queue I/O parameter Pl. To 
enable an AST, Pl contains the address of an AST routine. The routine 
allocates a control block that can double as an AST control block when 
the AST is delivered. 


This control block contains the following information: 

e The address of the specified AST routine 

e The specified AST parameter 

e The specified access mode 

e The channel number 

e The process identification of the requesting process 
COMSSETATTNAST links the control block to the start of the specified 
linked list of AST control blocks located in the unit control block 
extension area. 
If Pl is clear, the routine disables ASTs by searching through’ the 


linked list, extracting each entry, and deallocating it. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the IRP 

R4 Address of the current PCB 

R5 Address of the UCB 

R6 Address of the assigned channel control block 

R7 Address of the specified AST control block 
listhead 

AP Address of the QIO parameter list 


OPERATING SYSTEM ROUTINES 


Fields Contents 

IRPSW_CHAN I/O request channel number 

UCBSB_DIPL Device IPL 

PCBSW_ASTCNT Number of ASTsS remaining in process quota 
PCBSL_ PID Process identification 

0 (AP) Process AST address 

4 (AP) AST parameter 

8 (AP) Access mode for AST 


IPL at execution: caller's IPL and device IPL 

If the process exceeds buffered I/O or AST quotas, or if there is no 
memory available to allocate an AST control biock, this routine 
transfers control to EXESABORTIO with error status. 


If Pl is clear, the routine transfers control to COMSFLUSHATTNS~ to 
remove the identified AST control block. 


This routine exits to its caller. 


OUTPUT FROM ROUTINE 
Registers Contents 
RO SSS NORMAL (success) 


SS$_EXQUOTA 
SS$_INSFMEM 


Rl Destroyed 

R2 Destroyed 

R3 Address of the IRP 
R5 Address of the UCB 
R6 Destroyed 

R7 Destroyed 

R8 Destroyed 

Fields Contents 
DCBSW_ASTCNT Decreased by l 
Specified listhead Updated 


IPL at exit: caller's IPL 


OPERATING SYSTEM ROUTINES 


ERLSDEVICERR in module ERRORLOG 


Logs a controller and/or device error. This routine allocates an 


error message buffer and writes data from the I/O request packet and 
unit control block. It also calls the driver register dump routine 
for device registers. 


INPUT TO ROUTINE 


Registers Contents 
R5 Address of unit control block 


ERLSDEVICERR sets the error type code to device error. This routine 
uses fields in the UCB, DDB, DDT, and I/O request packet. It also 
assumes that the driver contains a register dump routine. It uses the 
DDT to calculate the address of the register dump routine and then 
calls it. 


If you do not specify a dump routine in the DDTAB macro’ invocation, 


DDTAB supplies the address of IOCSRETURN. IOCSRETURN simply returns; 
it is a NOP. 


OUTPUT FROM ROUTINE 


Registers Contents 

Fields Contents 

UCBSL_EMB Address of the error message buffer 
UCBSW_STS Shows error log in progress 


ERLSDEVICTMO in module ERRORLOG 
Logs a device timeout. This routine performs the same functions’ and 


uses the same input and output as ERLSDEVICERR with one exception: 
the error type code is device timeout. 


ERLSRELEASEMB in module ERRORLOG 


Wakes the error log process to write the contents of an error message 
buffer into the error logging file. 


INPUT TO ROUTINE 


Registers Contents 

R2 Address of error message buffer 

Fields Contents 

ERLSV_TIMER Determines whether a timer is running on the 
(in ERLS$GB_BUFFLAG) buffer 


IPL at execution: caller's IPL 


OPERATING SYSTEM ROUTINES 


OUTPUT FROM ROUTINE 


Registers Contents 
RO Destroyed 
Fields Contents 
Busy message count Decreased by 1 


(in ERL$B_BUSY) 


Complete message Incremented by 1 


count (in error message 
buffer header) 


If ERL$B MSGCNT is greater than the maximum message count, this 
routine wakes the error logger. 


IPL at exit: caller's IPL 


EXESABORTIO in module SYSQIOREQ 


FDT routines jump to this routine to finish an I/O operation without 
returning final I/O status in the IOSB. This routine zeroes the IOSB 
field of the I/O request packet, clears a bit to prevent a user mode 
AST, and inserts the I/O request packet in the I/O postprocessing 
queue. 


INPUT TO ROUTINE 


Registers Contents 

RO First longword of status for I/O status block 
R3 Address of I/O request packet 

R4 Address of current PCB 

R5 Address of UCB 

Fields Contents 

ACBSV_QUOTA Set to 1 (when an AST is specified) 


(in IRP$B_RMOD) 


IPL at execution: IPL$_ASTDEL 


OUTPUT FROM ROUTINE 

Registers Contents 
None written --- 
Fields Contents 


ACBSV_QUOTA Cleared to zero (if field previously set) 
(in IRP$B_RMOD) 


IRPSL_IOSB Zero 


OPERATING SYSTEM ROUTINES 


PCBSW_ASTCNT Incremented if ACBSV_ QUOTA was set 


EXESABORTIO places the I/O request packet into the I/O postprocessing 
queue headed by IOCSGL PSBL. 


IPL at exit: 0 (normal process IPL) 
EXESALLOCBUF in module MEMORYALC 


FDT routines call this routine to allocate a buffer for a buffered I/0 
operation from the nonpaged system pool. This routine can place the 
process in a resource wait state if sufficient memory is _ not 
available, and the process has resource wait mode enabled. The caller 
must adjust process quotas. 


INPUT TO ROUTINE 


Register Contents 

Rl Size of requested buffer in bytes 

R4 Address of current PCB 

Fields Contents 

PCBSV_SSRWAIT One or zero. Determines whether process 


should wait, if no memory available for 
requested buffer. If this field is set, 
resource wait mode is disabled. 


IPL at execution: caller's IPL, IPL 11, and IPLS SYNCH 


OUTPUT FROM ROUTINE 
Registers Contents 


RO SSS NORMAL (success) 
SS$_INSFMEM 


Rl Size of allocated buffer (requested size is 
rounded up to next 16-byte multiple) 


R2 Address of allocated buffer 
R3 Destroyed 

Fields Contents 

IRPSW SIZE Buffer size in bytes 


(in allocated buffer) 


IRPSB TYPE DYNSC_BUFIO 
(in allocated buffer) 


IPL at exit: IPLS$ ASTDEL 


OPERATING SYSTEM ROUTINES 


EXESALLOCIRP in module MEMORYALC 
This routine allocates an I/O request packet from nonpaged dynamic 
memory. It performs the same functions and has the same input and 
output as EXESALLOCBUF, with the following exceptions: 

e The caller does not specify a buffer size 

e The allocated buffer is IRPSC_LENGTH bytes long 

e The buffer size is set to IRPSC_LENGTH 


e The buffer type is set to DYNSC_IRP 


EXESALONONPAGED in module MEMORYALC 


Driver fork processes use this routine to allocate a block of memory 
from the nonpaged system pool. 


The block header is not initialized. 


INPUT TO ROUTINE 


Registers Contents 

Rl Requested block size in bytes 
Fields Contents 

none --- 


IPL at execution: caller's IPL and IPL 1l 


OUTPUT FROM ROUTINE 


Registers Contents 
RO Status code (0 or lL) 
Rl Size of allocated buffer (requested size 


rounded up to next 16-byte multiple) 


R2 Address of allocated block 
R3 Destroyed 
Fields Contents 


IPL at exit: caller's IPL 


EXESALTQUEPKT in module SYSQIOREQ 


Driver FDT routines and fork processes call this routine to send an 
I/O request packet to a driver's alternate start I/O routine so that 
it bypasses the I/O request queue for the device's unit control block. 
EXESALTQUEPKT passes the address of the I/O request packet to the 
driver without regard for the status of the device unit. 


OPERATING SYSTEM ROUTINES 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the I/O request packet 

R5 Address of the unit control block 

Fields Contents 

DDTSL_ALTSTART Address of the alternate start I/O routine 
UCBSB_ FIPL Driver fork IPL 

UCBSL_ DDB Address of unit's DDB 

DDBSL_DDT Address of the driver dispatch table 


IPL at execution: UCBSL_ FIPL 


EXESALTQUEPKT calls the alternate start I/O routine and returns to its 
caller. 


OUTPUT FROM ROUTINE 


Registers Contents 
RO Destroyed 
Rl Destroyed 
R2-R5 Destroyed 


IPL at exit: caller's IPL 


EXESBUFFRQUOTA in module EXSUBROUT 


FDT routines call this routine to determine whether a= process's 
buffered byte count quota usage permits the process to be granted 
additional buffered I/O. This routine may place the process in a 
resource wait state if quota usage is too large, and the process has 
resource wait mode enabled. 


INPUT TO ROUTINE 


Registers Contents 
Rl Number of requested bytes 
R4 Address of PCB 


OPERATING SYSTEM ROUTINES 


Fields Contents 


PCBSV_SSRWAIT When process exceeds quota, determines 


whether process’ should wait. If this field 
is set, resource wait mode is disabled. 


IOCSGW_MAXBUF Maximum number of buffered I/0 bytes’ that 
system allows to any process 

JIBSL_BYTLM Process's byte count limit 

JIBSL BYTCNT Process's byte count usage quota 


IPL at execution: caller's IPL and IPLS SYNCH 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SSS NORMAL (success) 
SS$_EXQUOTA 

R3 Destroyed 

Fields Contents 


IPL at exit: IPLS$ ASTDEL 


EXESBUFQUOPRC in module EXSUBROUT 

EXESBUFQUOPRC performs the same function and has the same input = and 
output as EXESBUFFRQUOTA with the following exception: EXESBUFQUOPRC 
does not check the field IOCSGW MAXBUF. 

EXESDEANONPAGED in module MEMORYALC 


Deallocates a block of memory to the nonpaged system pool. 


This routine performs the same functions and has the same input and 
output as the routine COMSDRVDEALMEM, with the following exceptions: 


e R3 is destroyed 


e The caller's IPL must be at IPL$ QUEUEAST or lower 


OPERATING SYSTEM ROUTINES 


EXESFINISHIO in module SYSQIOREQ 


FDT routines transfer control to this routine to finish an I/0 
operation and return a quadword of final I/O status to the requesting 
process. This routine writes final I/O status into the I/O request 
packet and inserts’ the I/O request packet in the I/O postprocessing 
queue. 


INPUT TO ROUTINE 


Registers Contents 

RO First longword of status for the I/O status 
block 

Rl Second longword of status for the I/O status 
block 

R3 Address of the I/O request packet 

R4 Address of the current process control block 

R5 Address of the UCB 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SS$_NORMAL 

Fields Contents 

IRPSL_ MEDIA First longword of I/O status (R0) 
IRPSL MEDIA+4 Second longword of I/O status (R1) 
UCBSL_OPCNT Incremented by 1 


This routine places the I/O request packet into the I/O postprocessing 
queue headed by IOCSGL PSBL. 


EXESFINISHIOC in module SYSQIOREQ 

This routine performs the same functions and has the same input and 
output as EXESFINISHIO with the following exception: EXESFINISHIOC 
clears the contents of Rl before storing RO and R1 in the I/O request 
packet. 


EXESFORK in module FORKCNTRL 


This routine performs the same functions as EXESIOFORK except’ that 
this routine does not disable timeouts by clearing UCBSV_ TIM in the 
UCBSW_STS field of the unit control block. 
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OPERATING SYSTEM ROUTINES 


EXESFORKDSPTH in module FORKCNTRL 


The interrupt service routine that dispatches fork processes in a fork 
queue. This routine gains control when the processor grants a 
software interrupt at IPLs 6 and 8 through 11. When EXESFORKDSPTH 
gains control the stack contains the following information: 


e O(SP) contains the PC at the time of the interrupt 
e 4(SP) contains the PSL at the time of the interrupt 


RO through R5 at the time of the interrupt are also saved by 
EXESFORKDSPTH. 


SWISGL_ FQFL indexed by the current IPL contains the address of the 
head of the fork queue for this IPL. Each entry in the fork queue is 
the address of a fork block that contains R3, R4, a PC, and implicitly 
R5; R5 is the address of the fork block. 


If the queve is empty when the interrupt occurs, EXESFORKDSPTH 
dismisses the interrupt without error. 


EXESFORKDSPTH empties the fork queue corresponding to the IPL of the 
interrupt. For each queue entry, it restores R3 and R4 from the fork 
block, saves the dispatch address and IPL on the stack, and executes a 


JSB to the saved PC address. When the queue is empty, it dismisses 
the interrupt. 


The IPL on return from each fork process must equal the IPL at which 


the process waS called. If IPL does not match, EXESFORKDSPTH signals 
the fatal bugcheck BADFORKIPL. 


EXESINSERTIRP in SYSQIOREQ.MAR 
Inserts an I/O request packet according to the base priority of the 


I/O request packet's originating process into the I/O request packet 
walt queue of a unit control block. 


INPUT TO ROUTINE 


Register Contents 

R2 Address of the I/O queue list head for the 
device 

R3 Address of the I/O request packet 

Fields Contents 


IPL at execution: caller's IPL (fork level or higher) 
OUTPUT FROM ROUTINE 
Register Contents 


Rl Destroyed 


OPERATING SYSTEM ROUTINES 


This routine places the I/O request packet in the queue and sets the Z 
condition code in the PSL as follows: 


1 indicates that the entry is first in the queue. 

O indicates that at least one entry was already in the queue. 
IPL at exit: caller's IPL 
EXESINSIOQ in SYSQIOREQ.MAR 
Examines the unit control block. If the device is idle, this routine 


calls IOCSINITIATE; if the device is busy, it calls EXESINSERTIRP. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the I/O request packet 
R5 Address of the UCB 

Fields Contents 

UCBS$B_ FIPL Driver fork IPL 

UCBSV_BSY Determines whether device is busy 


(in UCBSW_STS) 
UCBSL_ IOQFL Address of device I/O queue listhead 


IPL at execution: driver fork level 


OUTPUT FROM ROUTINE 


Registers Contents 
RO Destroyed 
R1 Destroyed 
R2 Destroyed 


Additional registers used by the driver start I/O routine will be 
destroyed if the start I/O routine is called. 


Fields Contents 


UCBSV_BSY Set to l 
(in UCBSW_ STS) 


IPL at exit: original IPL 


OPERATING SYSTEM ROUTINES 


EXESIOFORK in module FORKCNTRL 


Saves the contents of R3 and R4 in the fork block specified by R5. 


This routine pops the return PC off the top of stack and saves the PC 
value in the fork block. It inserts the fork block address into’ the 
fork queue corresponding to the IPL stored in the fork block. 


INPUT TO ROUTINE 


Register Contents 

R5 Address of the fork block (usually the UCB) 
0 (sp) Return address of caller 

4(sp) Return address of caller's caller 

Fields Contents 

FKBSB_FIPL Fork IPL 


(in fork block) 
IPL at execution: caller's IPL 


OUTPUT FROM ROUTINE 


Registers Contents 
R3 Destroyed 
R4 FKBSB_FIPL 
Fields Contents 
UCBSV_TIM Zero 

(in UCBSW_STS) 

FKBSL_FR3 R3 

(in UCB) 

FKBSL_FR4 R4 

(in UCB) 

FKBSL_ FPC 0 (SP) 

(in UCB) 


The routine queues the UCB address to the list headed by SWISGL FOFL. 
If the queue is empty, requests a software interrupt at fork IPL. 


IPL at exit: caller's IPL 


OPERATING SYSTEM ROUTINES 


EXESMODIFY in module SYSQIOFDT 
FDT routines transfer control to this device-independent routine that 
validates and readies a user buffer for a DMA read/write operation. 
Use EXESMODIFY instead of EXESREAD when you wish your driver to read 
and write to a buffer. EXESMODIFY disables a paging mechansim used 
during write-only operations. 
This routine performs the following functions: 

e Translates read logical functions to read physical functions 

e Transfers queue I/O parameters to the I/O request packet 


e Verifies that the caller has access to the specified buffer 


e Locks the buffer's pages into physical memory. If a page 


fault occurs during this step, the routine returns control to 
the Queue I/O Request system service, which repeats’ the 
request. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the I/O request packet 

R4 Address of the current PCB 

R5 Address of the UCB assigned to the device 
unit 

R6 Address of the CCB for the channel assigned 
to the device unit 

R7 Bit number of the I/O function code 

R8 FDT entry address 

AP Address of the first function-dependent QIO 
parameter (P11) 

Fields Contents 

0 (AP) Virtual address of buffer (P1) 

4 (AP) Number of bytes in transfer (P2) 

12 (AP) Carriage control byte (P4) 

IRPSW_FUNC I/O function code 


IPL at execution: 


If this routine 
EXESQIODRVPRT. 
EXESABORTIO. 


caller's IPL (IPLS ASTDEL) 


completes successfully, it transfers control to 
EXESMODIFY fails, it transfers control to 


OUTPUT FROM ROUTINE 


OPERATING SYSTEM ROUTINES 


Registers Contents 
RO, Rl, R2 Destroyed 
Fields Contents 
IRPSB_CARCON P4 


IRPS$V_FUNC 


Set to 1 (indicates a read function) 


(in IRPSW_STS) 


IRPSL SVAPTE Address of page table entry that maps’ the 


first page of the buffer 
IRPSW_BCNT Size of the transfer in bytes 


IPL at exit: caller's IPL 


EXESMODIFYLOCK in module SYSQIOFDT 


FDT routines call EXESMODIFYLOCK to perform buffer processing on a DMA 
transfer. This routine: 


@e Determines whether the caller has write access to the buffer 


e Locks the buffer's pages into memory. If a page fault occurs 
during this process, the routine returns control to the Queue 
I/O Request system service, which resubmits the request. 


Use EXESMODIFYLOCK instead of EXESREADLOCK when you expect your driver 


to read and write to a buffer. EXESMODIFYLOCK disables a paging 
mechanism used in write-only operations. 


INPUT TO ROUTINE 


Registers Contents 

RO Starting address of buffer 

Rl Size of transfer in bytes 

R3 Address of the I/O request packet 
R4 Address of current PCB 

R6 Address of the CCB 

Fields Contents 


IPL at execution: caller's IPL (IPLS ASTDEL) 


OPERATING SYSTEM ROUTINES 


If EXESMODIFYLOCK fails, it transfers control to EXESABORTIO. If the 
routine completes successfully, control passes to EXESQIODRVPKT. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SS$_NORMAL 

Rl Address of the PTE that maps the first page 
of the buffer 

R2 Destroyed 

R3 Address of the IRP 

Fields Contents 

IRPSL_ SVAPTE Address of the PTE that maps the first page 
of the buffer 

IRPSW_BCNT Size of the transfer in bytes 

IRPSV FUNC A value of 1 (indicating a read function) 


(in IRPSW_STS) 


IPL at exit: caller's IPL 


EXESMODIFYLOCKR in module SYSQIOFDT 


This routine determines whether a process has write access to the 
buffer pages it requested, then, if access is permitted, it locks the 
pages into memory. If the access check or page locking procedure 
fails, the routine calls the driver to clean up QIO bookkeeping. 


Drivers typically use EXESMODIFYLOCKR when they must lock multiple 
areas into memory for one I/O request, and then need to unlock 


previously locked areas after a QIO is aborted. 


INPUT TO ROUTINE 


Registers Contents 

RO Starting address of buffer 

Rl Length of the buffer in bytes 

R3 Address of the IRP 

R4 Address of the current process's PCB 
R6 Address of the channel control block 
Fields Contents 


OPERATING SYSTEM ROUTINES 


EXESMODIFYLOCKR may fail for a number of reasons: 


e The buffer access check fails. In this case, the routine 
returns SS$ ACCVIO to the driver in RO. 


e The caller process has an insufficient working set limit to 


lock all the buffer pages into memory. The routine returns 
SSS _INSFWSL in RO. 


e A page fault occurs while the routine is locking pages’ into 
memory. The status returned in RO in this caSe is zero. 


If any of the above errors occur, the routine calls back the driver as 
a coroutine with error status in RO and all other registers preserved. 
The driver performs necessary queue I/O cleanup, that is, it carries 


out any procedures that the system does not perform as part of the 
normal QIO abort processing. 


The driver must preserve all registers, including RO and Rl. 


When the driver returns by executing an RSB instruction, 
EXESMODIFYLOCKR aborts the I/O request if RO contains an error status, 
then performs processing that results in the I/O request's' being 
resubmitted to the driver. For example: 


JSB G° EXESMODIFYLOCKR 
BLBS BUF _LOCK_OK 


BUF_LOCK_FAIL: 
<clean up this QIO bookkeeping> 
RSB 


BUF LOCK OK: 
~ <continue this QIO> 


If the subroutine is successful, it returns control to its caller. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SS$ NORMAL (1) 

Rl Address of the PTE that maps the first page 
of the buffer 

R2 Function indicator (set to 1) 

R3 Address of the IRP 

Fields Contents 

IRPSL SVAPTE Address of the PTE that maps the first page 
of the buffer 

IRPSW_BCNT Size of the transfer in bytes 

IRP$M_FUNC Set to 1 


(in IRPSW_FUNC) 


IPL at exit: caller's IPL 


OPERATING SYSTEM ROUTINES 


EXESONEPARM in module SYSQIOFDT 


Device-independent FDT routine that copies a single QIO parameter into 
the I/O request packet and calls EXESQIODRVPRT. 


INPUT TO ROUTINE 


Registers 


R3 


R4 


R5 


R6 


R7 


R8 


AP 


Fields 


OUTPUT FROM ROUTINE 
Registers 
Fields 


IRPSL MEDIA 
(of IRP) 


Contents 


Address of the I/O request packet for’ the 
current I/O request 


Address of the process control block of the 
Current process 


Address of the unit control block of the 
device assigned to the user-specified process 
I/O channel 

Address of the channel control block that 
describes the user-specified process I/0 
channel 


Bit number of the uSer-specified I/O function 
code 


Address of FDT entry 


Address of the first function-dependent 
parameter specified in the user's request 


Contents 


Contents 


Contents 


Pl 


IPL at exit: caller's IPL 


This routine exits to EXESQIODRVPKT. 


Chapter 8 provides more information about this routine. 


EXESQIODRVPKT in module SYSQIOREQ 


FDT routines call this routine to send an IRP to a driver start I/0 


routine. 
EXESQIORETURN. 


This routine calls EXESINSIOO and then transfers control to 


OPERATING SYSTEM ROUTINES 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the I/O request packet 

R4 Address of the process control block 
R5 Address of the unit control block 
Fields Contents 

UCBSB_ FIPL Driver fork IPL - 

UCBSV BSY Unit busy flag 


(in UCBSW_STS) 


UCBSL_ IOQFL Address of unit I/O queue listhead 


EXESQIORETURN in module SYSQIOREQ 
Sets a success status code in RO, lowers IPL to 0, and returns to the 


system service dispatcher. 


OUTPUT FROM ROUTINE 
Registers Contents 
RO SS$_ NORMAL 


IPL at exit: 0 


This routine returns by issuing a RET instruction. 


EXESREAD in module SYSQIOFDT 


Device-independent FDT routine that validates and readies a user 
buffer for a DMA read operation. This routine performs the same 
functions and has the same input and output as EXESMODIFY, with a 
Single exception noted in the description of EXESMODIFY. 


EXESREADCHK in module SYSQIOFDT 


Checks pages for write accessibility by a process. This routine 
writes the total byte count of a transfer into the I/O request packet. 


If pages do not allow write access, the routine transfers control to 
EXESABORTIO, which terminates the request with access’ violation 
status. If EXESREADCHK completes successfully, control returns to its 
caller. 


OPERATING SYSTEM ROUTINES 


INPUT TO ROUTINE 


Registers Contents 

RO Address of buffer 

Rl Size of the transfer in bytes 

R3 Address of the I/O request packet 
Fields Contents 


IPL at execution: caller's IPL 


OUTPUT FROM ROUTINE 


Registers Contents 

RO Address of buffer (success) 

Rl Size of transfer in bytes 

R2 Value of 1 (to indicate a read) 

R3 Address of IRP 

Fields Contents 

IRPSW_BCNT Size of transfer in bytes 

IRPSV_FUNC Value of 1 (indicates a read function) 


(in IRPSW_STS) 


IPL at exit: caller's IPL 


EXESREADCHKR in module SYSQIOFDT 


This routine performs the same function aS EXESREADCHK, except that, 
upon error, it calls the driver FDT routine back as a coroutine to 
clean up QIO bookkeeping. See the description of error procedures’ in 
EXESMODIFYLOCKR for further information. 


EXESREADLOCK in module SYSQIOFDT 


FDT routines call this routine to check buffer accessibility and lock 
the user buffer in memory for a DMA read transfer. This routine 
performs the same functions and has the same input and output as 
EXESMODIFYLOCK, except that it is used when the driver performs only a 
read I/O function. 


EXESREADLOCKR in module SYSQIOFDT 


This subroutine determines whether a process has write access to 
requested buffer pages and, if access is permitted, it locks those 
pages into memory. EXESREADLOCKR performs the same functions and has 
the same input and output as EXESMODIFYLOCKR. 


OPERATING SYSTEM ROUTINES 


EXESSENSEMODE in module SYSOQIOFDT 
Device-independent FDT routine that copies device-dependent 


characteristics from the device's UCB into Rl. This routine writes a 
Success code into RO and transfers control to EXESFINISHIO. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the I/O request packet for’ the 
current I/O request 

R4 Address of the PCB of the current process 

R5 Address of the UCB of the device assigned _ to 
the user-specified process I/O channel 

R6 Address of the CCB that describes the 
user-specified process I/O channel 

R7 Bit number of the user-specified I/O function 
code 

R8 Address of function decision table dispatch 

AP Address of the first fFunction-dependent 
parameter specified in the user's request 

Fields Contents 

UCBSL_ DEVDEPEND Device-dependent status 


IPL at execution: caller's IPL 


OUTPUT FROM ROUTINE 


Registers Contents 
RO SS$_NORMAL 
Rl Device-dependent characteristics copied from 


UCBS$L_DEVDEPEND 


Fields Contents 


IPL at exit: caller's IPL 
This routine exits to EXESFINISHIO. 


For additional information, refer to Chapter 8. 


OPERATING SYSTEM ROUTINES 


EXESSETCHAR in module SYSQIOFDT 
Device-independent FDT routine that writes a quadword whose address is 


QIO parameter Pl into the device's unit control block. Writes a 
success code into RO and transfers control to EXESFINISHIO. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the IRP for the current I/0 
request 

R4 Address of the current PCB 

R5 Address of the UCB of the assigned device 
unit 

R6 Address of the CCB that describes the 


specified process I/O channel 


R7 Bit number of the I/O function code 

R8 Address of the FDT dispatcher 

AP Address of the first function-dependent QIO 
parameter 

Fields Contents 

0 (AP) Address of new device characteristics (Pl) 


IPL at execution: caller's IPL 

If this routine fails because the user lacks read access to the 
characteristics quadword, control transfers to EXESABORTIO with access 
violation status. 

If EXESSETCHAR completes successfully, it transfers’ control to 
EXESFINISHIO. 


OUTPUT FROM ROUTINE 


Registers Contents 
RO SS$_NORMAL (success) 

SSS _ACCVIO (failure) 
Fields Contents 
UCBSB_DEVCLASS Byte 0 of quadword 
UCBS$B_DEVTYPE Byte 1 of quadword 
UCBSW_DEVBUFSIZ Bytes 2 and 3 of quadword 
UCBSL DEVDEPEND Bytes 4 through 7 of quadword 


IPL at exit: caller's IPL 


Refer to Chapter 8 for additional information on this routine. 


OPERATING SYSTEM ROUTINES 


EXESSETMODE in module SYSQIOFDT 


Device-independent FDT routine that writes a quadword whose address is 
a QIO parameter into the I/O request packet and calls EXESQIODRVPKT. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the I/O request packet for’ the 
current I/O request 

R4 Address of the PCB of the current process 

R5 Address of the UCB of the device assigned _ to 
the user-specified process I/O channel 

R6 Address of the CCB that describes the 
user-specified process I/O channel 

R7 Bit number of the I/O function code 

R8 Address of the FDT entry 

AP Address of the first function-dependent QIO 
parameter 

Fields Contents 

PO (AP) Address of a quadword of device 


characteristics 
IPL at execution: caller's IPL 
If the user lacks read access to the device characteristics quadword, 
the routine transfers control to EXESABORTIO with access violation 


Status. If EXESSETMODE completes successfully, it normally exits to 
EXESQIODRVPKT. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SSS NORMAL (success) 
SS$_ACCVIO 

Fields Contents 

IRPSL MEDIA First longword of device characteristics 
quadword 

IRPSL MEDIA+4 Second longword of device characteristics 
quadword 


IPL at exit: caller's IPL 


For more information about this routine, refer to Chapter 8. 


OPERATING SYSTEM ROUTINES 


EXESSNDEVMSG in module MBDRIVER 
Driver fork processes call this routine to send messages to system 


processes such as OPCOM. This routine constructs a message on the 
stack and calls EXESWRTMAILBOX to send the message to a mailbox. 


INPUT TO ROUTINE 


Registers Contents 

R3 Address of the mailbox UCB 
R4 Message type 

R5 Address of the UCB 

Fields Contents 

UCBSW_INIT Device unit number 

UCBSL_ DDB Address of device DDB 
DDBST_ NAME Device controller name 


Mailbox UCB fields 
IPL at execution: caller's IPL and IPLS MAILBOX 
This routine can fail for one of the following reasons: 
e The message is too large for the mailbox 
e The message mailbox is full of messages 
e The system is unable to allocate memory for the message 


If any of the above conditions occur, EXESSNDEVMSG returns’ error 
status to the caller. 


If EXESSNDEVMSG completes successfully, it exits with an RSB 
instruction. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SS$_ NORMAL (success) 
SSSMBTOOSML 
SSSMBFULL 
SSSINSFMEM 

Rl Destroyed 

R2 Destroyed 

R3 Destroyed 

R4 Destroyed 

R5 Destroyed 


OPERATING SYSTEM ROUTINES 


Fields Contents 


IPL at exit: caller's IPL 


EXESWRITE in module SYSQIOFDT 


Device-independent FDT routine that validates and readies a _ user 
buffer for a DMA write operation. This routine performs the same 
steps as EXESMODIFY, and has the same input and output. 


EXESWRITECHK in module SYSQIOFDT 


Checks pages for read accessibility by a process and writes the total 
byte count of a transfer into the I/O request packet. If pages do not 
allow read access, the routine transfers control to EXESABORTIO, which 
terminates the request with access violation status. If EXESWRITECHK 
completes successfully, it exits to its caller. 


INPUT TO ROUTINE 


Registers Contents 

RO Address of buffer 

Rl Size of the transfer in bytes 

R3 Address of the I/O request packet 


IPL at execution: caller's IPL 


OUTPUT FROM ROUTINE 


Registers Contents 

RO Buffer address (success) 

Rl Size of the transfer in bytes 

R2 Cleared (indicates a write function) 
R3 Address of the I/O request packet 
Fields Contents 

IRPSW_BCNT Contains transfer size in bytes 


IPL at exit: caller's IPL 


EXESWRITECHKR in module SYSQIOFDT 


This routine performs the same functions as EXESWRITECHK, except that, 
upon error, it calls the driver FDT routine back as a coroutine to 
clean up QIO bookkeeping. 


See the description of error procedures in EXESMODIFYLOCKR for more 
information about coroutine cleanup. 


OPERATING SYSTEM ROUTINES 


EXESWRITELOCK in module SYSQIOFDT 
FDT routines call this routine to determine whether the caller has 


read access to the buffer and to lock the buffer in memory for a DMA 
write transfer. 


INPUT TO ROUTINE 


Register Contents 

RO Starting address of I/O buffer 

Rl Length of transfer in bytes 

R3 Address of the I/O request packet 
R4 Address of the PCB 

R6 Address of the CCB 

Fields Contents 


IPL at execution: caller's IPL (IPLS$ ASTDEL) 


This routine calls EXESWRITECHK and MMGSIOLOCK. MMGSIOLOCK locks 
pages in memory. If EXESWRITELOCK fails because a page fault occurs 
during the locking procedure, it transfers control to the Queue [I/O 
Request system service, which repeats the I/O request. It exits to 
EXESABORTIO if it cannot complete successfully. If the routine does 
complete without error, it exits to EXESQIODRVPKT. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SS$_NORMAL 

Rl Address of the PTE that maps the first page 
of the buffer 

R2 Destroyed 

R3 Address of the IRP 

Fields Contents 

IRP$SL SVAPTE Address of the PTE that maps the first page 
of the buffer 

IRPSW_BCNT Size of the transfer in bytes 

IRPSV FUNC A value of 0 (indicating a write function) 


(in IRPSW_ STS) 


IPL at exit: caller's IPL 


OPERATING SYSTEM ROUTINES 


EXESWRITELOCKR in module SYSQIOFDT 


This routine determines whether the process has read access to. the 


requested buffer pages, and, if access is permitted, it locks those 
pages into memory. EXESWRITELOCKR performs the same functions as 
EXESMODIFYLOCKR, with the following exceptions: 


e R2, on output, contains a zero to indicate a write function. 
e IRPSM_FUNC (in IRPSW_FUNC) is clear (zero) to indicate a write 
function) 
EXESZEROPARM in module SYSQIOFDT 
Device-independent FDT routine that clears the parameter field of the 
IRP and calls EXESQIODRVPRKT. 
INPUT TO ROUTINE 
Register Contents 


R3 Address of the I/O request packet for’ the 
current I/O request 


R4 Address of the process control block of the 
current process 


R5 Address of the unit control block of the 
: device assigned to the user-specified process 
I/O channel 


R6 Address of the channel control block that 
describes the user-specified process I/0 
channel 

R7 Bit' number of the user-specified I/O function 
code 

R8 Address of FDT entry 

AP Address of the first function-dependent 


parameter specified in the user's request 


Fields Contents 


IPL at execution: caller's IPL 


This routine exits by transferring control to EXESQIODRVPRT. 


OUTPUT FROM ROUTINE 


Registers Contents 
Fields Contents 
IRPSL MEDIA Zero 


IPL at exit: 


OPERATING SYSTEM ROUTINES 


caller's IPL 


For additional information, refer to Chapter 8. 


IOCSALOUBAMAP(N) in module IOSUBNPAG 


This routine searches the map register bit map in the adapter control 
block to allocate a set of contiguous map registers to a driver fork 


process. 


INPUT TO ROUTINE 
Registers 


R3 


R5 
Fields 


UCBSW_BCNT 
UCBSW_BOFF 


UCBSL_ CRB 


CRBSL_INTD+ 
VECSL_ADP 


VECSV_MAPLOCK 

(in CRBSL_INTD 
+VECSW_MAPREG) 
ADPSW_MRBITMAP 


IPL at execution: 


If map registers are already permanently allocated to the 


Contents 


Number of map registers to allocate (if entry 


is IOCSALOUBAMAPN) 
Address of the UCB 
Contents 


Transfer byte count (if 


LOCSALOUBAMAP) 


Byte offset in page (if 
ITOCSALOUBAMAP) 


Address of the CRB 


entry is 


entry is 


Address of the device's adapter control block 


Bit that indicates whether map registers are 
permanently allocated to this controller 


Determines which map registers are available 


caller's IPL 


controller, 


this routine exits successfully without allocating any map registers. 
Otherwise, the routine searches the map register bit 


required number of contiguous map registers, 


exits by issuing an RSB instruction. 


OUTPUT FROM ROUTINE 
Registers 


RO 


Rl 


R2 


Contents 


1 (success) 


map for the 
calls IOCSALTUBAMAP, and 


0 (insufficient contiguous map registers) 


Destroyed 


Destroyed 


Fields 


CRBSL_INTD+ 
VECS$B_NUMREG 


CRBSL_INTD+ 
VECSW_MAPREG 


ADPSW_MRBITMAP 


OPERATING SYSTEM ROUTINES 


Contents 


Number of map registers allocated 


Starting map register number 


Bits for allocated map registers set to zero. 


IPL at exit: caller's IPL 


IOCSALTUBAMAP in module IOSUBPAG 


Clears or sets a field of bits in the UNIBUS adapter map register 


allocation bit map. 


Register 


RO 


Rl 
R2 
R4 
Fields 


CRBSL_INTD+ 
VECSB_NUMREG 


IPL at execution: 


OUTPUT FROM ROUTINE 
Registers 

R3 

R4 

Fields 


ADPSW_MRBITMAP 


Contents 


Alternation bit mask (zeros to clear bits, 
ones to set bits) 


Address of the channel request block 
Address of the adapter control block 
Number of the starting map register 
Contents 


Number of map registers needed 


caller's IPL 


Contents 
Destroyed 
Destroyed 
Contents 


Bits describing available map registers 


IPL at exit: caller's IPL 


C=31 


OPERATING SYSTEM ROUTINES 


IOCSAPPLYECC in module IOSUBRAMS 


Disk drivers call this routine to apply an ECC correction to data 


transferred from a device into memory. This routine corrects the data 
by exclusive ORing a correction pattern from the unit control block. 


It also sets a UCB bit to indicate that an ECC correction has been 
made. 


INPUT FROM ROUTINE 
Register Contents 
RO Number of bytes of data that have been 


transferred, not including the block to be 
corrected; this must be a multiple of 512 


bytes 
R5 Address of the unit control block 
Fields Contents 
UCBSW_BCNT Length of transfer in bytes 
UCBSW _ECl Starting bit number of the error burst 
UCBSW_EC2 Exclusive OR correction pattern 
UCBSL_SVPN Address of the system page table entry of a 


page that is available for use by driver 


UCBSL_SVAPTE System virtual address of the page table 
entry that maps the transfer 


IPL at execution: caller's IPL 


OUTPUT FROM ROUTINE 


Registers Contents 

RO Destroyed 

Rl Destroyed 

R2 Destroyed 

Fields Contents 

UCBSV_ECC Set to 1 to show that an ECC correction 
(in UCBSW_DEVSTS) was made 


IPL at exit: caller's IPL 


G=32 


OPERATING SYSTEM ROUTINES 


IOCSCANCELIO in IOSUBNPAG.MAR 


Device-independent cancel I/O routine that sets a cancel I/0 bit in 


the unit control block if the I/O request packet being currently 
processed on the device originates from the current process on the 
specified channel and the unit is busy. 


INPUT TO ROUTINE 


Register Contents 

R2 Negative of the channel number 

R3 Address of the I/O request packet 

R4 Address of the current PCB 

R5 Address of the unit control block 

Fields Contents 

IRPSL PID Process identification of the process”) that 
queued the I/O request 

IRPSW_CHAN Negative of the channel number 

PCBSL PID Process identification of the process” that 


requested cancellation 


UCBSV_BSY Device busy flag 
(in UCBSW_STS) 


IPL at execution: caller's IPL 


OUTPUT FROM ROUTINE 


Registers Contents 
Fields Contents 
UCBSV CANCEL Set if I/O request Should be cancelled 


(in UCBSW_STS) 


IPL at exit: caller's IPL 


IOCSDIAGBUFILL in module IOSUBNPAG 


Driver fork processes call this routine to fill a diagnostic buffer, 
if the QIO specifies such a buffer. This routine writes completion 
time and final error counters into buffer. It also calls the driver 
register dump routine to fill the remainder of buffer. 


INPUT TO ROUTINE 
Registers 


R4 


R5 
Field 
UCBSL_IRP 


IRPS$V_DIAGBUF 
(in IRPSW STS) 


IRPSL_DIAGBUF 


UCBSB_ERTCNT 
UCBSL_DDB 
DDB$L_DDT 
DDT$L_REGDUMP 


EXESGQ SYSTIME 


DDTSL_REGDUMP 


IPL at execution: 


OPERATING SYSTEM ROUTINES 


Contents 


Address’) of the device's control/status 
register 


Address of the unit control block 
Contents 
Address of the current IRP 


Determines whether diagnostic buffer is 
present. If set, one exists. 


Address of the diagnostic buffer, if one is 
present 


Final error retry count 

Address of the device data block 

Address of the driver dispatch table 
Address of the driver register dump routine 


Current system time (time at I/O request 
completion) 


Address of the driver register dump routine 


caller's IPL 


This routine saves the system time and final error count in the 


diagnostic buffer. 


It then calls the driver register dump routine, 


and exits with an RSB instruction. 


OUTPUT FROM ROUTINE 


Registers 
RO 
Rl 
R2 
R3 
R4 
R5 


Fields 


Contents 

Destroyed 

Destroyed 

Address of the DDT 

Address of the I/O request packet 
Device CSR register 

Address of the unit control block 


Contents 


IPL at exit: caller's IPL 
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OPERATING SYSTEM ROUTINES 


IOCSINITIATE in module IOSUBNPAG 


Starts a driver fork process to process an I/O request’ packet. This 
routine writes the I/O request packet address and I/O request packet 
transfer parameters into the unit control block. It also clears 
device status bits. If the QIO specifies a diagnostic buffer, this 
routine writes system time into the buffer. It also executes a JMP 
instruction to transfer control to the driver start I/O routine. 


INPUT TO ROUTINE 


Register 
R3 

R5 
Fields 


IRPSL SVAPTE 


IRPSW_BOFF 
IRPSW_SIZE 


IRPSV_DIAGBUF 
(in IRPS$W_STS) 


IRP$L DIAGBUF 
EXESGQ SYSTIME 


UCBSL DDB 
UCBSL DDT 


DDTSL START 


IPL at execution: 


Contents 

Address of the I/O request packet 

Address of the unit control block 

Contents 

Address of system buffer (buffered I/0) or 
address of PTE that maps’ process’ buffer 
(direct I/O). 

Byte offset of start of buffer 


Size in bytes of transfer 


Determines whether a diagnostic buffer is 
present. This field is set if one exists. 


Address of the diagnostic buffer, if one is 
present 


Current system time (when I/0 processing 
began) | 


Address of DDB 
Address of DDT 


Address of driver start I/O routine 


caller's IPL 


IOCSINITIATE exits by jumping to the driver start entry specified in 
the driver dispatch table. 


OUTPUT FROM ROUTINE 


Registers 
RO 


Rl 


Contents 
Destroyed 


Destroyed 


C=35 


OPERATING SYSTEM ROUTINES 


Fields Contents 

UCBSL_IRP Address of the start of the I/O request 
packet 

UCBSL_ SVAPTE IRPSL_ SVAPTE 

UCBSW_BOFF IRPSW_BOFF 

UCBSW_BCNT IRPSW_BCNT 

UCBSV_CANCEL Zero 


(in UCBSW_STS) 


UCBSV_TIMOUT Zero 
(in UCBS$W_STS) 


diagnostic buffer Current system time (first quadword) 


IPL at exit: caller's IPL 


IOCSIOPOST in module IOCIOPOST 


Interrupt service routine that processes I/O request packets in an I/O 
postprocessing queue. This routine gains control when the processor 
grants a software interrupt at IPLS IOPOST. For each queue entry, it 
adjusts quota use and unlocks pages or deallocates write buffers. It 
queues a kernel mode AST to copy final I/O status to the IOSB, to copy 
buffered read data, and to deallocate read buffers. The AST kernel 
mode routine code is located in module IOCIOPOST. The kernel mode AST 
routine queueS a user mode AST if specified in the QIO. When the 
postprocessing queue is empty, IOCSIOPOST dismisses the interrupt. 


INPUT TO ROUTINE 


Registers Contents 

Fields Contents 

IOCSGL_ PSFL Head of the I/O postprocessing queue. This 
routine uses this field to locate fields in 
the IRP. 

IRPSL PID Process identification of the process” that 


initiated the I/O request. This routine uses 
this field to locate the PCB. 


IPL at execution: IPLS IOPOST, IPLS ASTDEL 


IOCSIOPOST generates different results for direct and buffered I/O. 
For direct I/0, the routine unlocks’ the pages locked for the I/0 
request and sets the Queue I/0 event flag. The pages unlocked include 
any pages defined in the IRP extension area descriptors (if an IRPE 
exists). For buffered I/O read functions, the routine copies the data 
From the system buffer to the process buffer, then releases the system 
buffer. It also sets a Queue I/O event flag, if one was requested. 


For both direct and buffered I/O, 


functions: 


OPERATING SYSTEM ROUTINES 


IOCSIOPOST performs the following 


e Copies the diagnostic buffer from system to process space and 
releases the system buffer 
e Copies I/O completion status (if requested) from the I/0 


request packet to the process's I/O status block 


e Queues an AST to the process, 


if one was requested 


e Deallocates the IRP and any IRP extensions 


Note that kernel mode ASTs handle much of 


above, 


the processing described 


IOCSLOADUBAMAP (A) in module LOADMREG 


Driver fork processes for DMA transfers call this routine to load 
required by 
frame number, the data path number, possibly the byte offset bit, 
longword access enable bit. 
have 


UNIBUS map registers 


possibly the 
enough map registers 


the 


page 
and 
that 


map 


the current transfer with a 


This routine confirms 


been allocated and sets the last 


register invalid to stop a wild transfer. 


INPUT TO ROUTINE 
Registers 


R5 


Contents 


Address of unit control block 


The data path and map registers are already allocated. 


Field 


UCBSW_BOFF 


UCBSW_BCNT 


UCB$L_CRB 


CRBSL_INTD+ 
VECSB_DATAPATH 


VECSV_LWAE 

(in CRBSL_INTD+ 
VECSB_DATAPATH) 
CRBSL_INTD+VECSL_NUMREG 
CRBSL_INTD+VECSL_ ADP 
UBASL_ MAP 


UCBSL_SVAPTE 


Contents 


Offset to the first byte in the first page of 
the transfer 


Number of bytes in the transfer 


Address of the controller's channel 


block 


request 


Number of the data path to be allocated 


Determines length of buffering. 
Set if longword buffering used 
quadword buffering) 


(instead of 


Number of map registers allocated 
Address of the adapter control block 
Address of the first UNIBUS map register 


Address 
page of 


of the page table entry for the first 
the transfer 


OPERATING SYSTEM ROUTINES 


OUTPUT FROM ROUTINE 


Registers Contents 
RO Destroyed 
Rl Destroyed 
R2 Destroyed 
Fields Contents 


Allocated map registers Byte offset is set for entry IOCSLOADUBAMAP 
(never set for IOCSLOADUBAMAPA) 


IPL at exit: caller's IPL 


IOCSPURGDATAP in module LIOSUB 


Device drivers using buffered data paths call this subroutine after a 


data transfer. IOCSPURGDATAP purges the UNIBUS adapter buffered data 
path as well as checking for and clearing purge errors. 


INPUT TO ROUTINE 


Registers Contents 
R5 Address of the UCB 
Fields Contents 


IPL at execution: caller's IPL 


This routine obtains the start of UNIBUS adapter register space using 
the following chain of pointers: 


UCBSL_ CRB ==> CRB$L_INTD+VECSL_ADP ==> ADPSL_CSR 


This routine extracts the caller's data path number (buffered or 
direct) from the channel request block. The routine then purges the 
data path and stores the contents of the data path register in Rl. 
IOCSPURGDATAP clears any purge errors in the data path register. It 
also sets the appropriate status in RO, computes the base of UNIBUS 
map registers, and writes the base into R2. 


A purge of data path 0 is legal and a NOP; it always results in 
Success Status. 


IOCSPURGDATAP alters RO through R3 but preserves all other registers. 


OPERATING SYSTEM ROUTINES 


OUTPUT FROM ROUTINE 
Registers Contents 


RO Low bit set (success) 
Low bit clear (failure) 


Rl Contents of data path after purge (for 
register dump routine) 

R2 Address of the start of UNIBUS map- registers 
(for the register dump routine) 

R3 Address of the CRB 

Fields Contents 


IPL at exit: caller's IPL 


IOCSRELCHAN in module IOSUBNPAG 


Driver fork processes call this routine to release controller data 
channels assigned to a device. If the channel wait queue contains 
waiting fork processes, this routine dequeues a process, assigns’ the 


channel to that process, restores R3 through R5, and reactivates the 
Suspended process. 


INPUT TO ROUTINE 


Register Contents 

R5 Address of the unit control block 
Fields Contents 

UCBSL_ CRB | Address of the channel request block 
CRBSL_LINK Address of the secondary CRB 
CRBSV_BSY Set if the channel is busy 

(in CRBSB MASK) 

CRBSL_INTD+VECSL_ IDB Address of the interrupt data block 
IDBSL_OWNER Channel's owner UCB address 

CRBSL WQFL Head of the queue of waiting UCBs 


IPL at execution: caller's IPL 


OUTPUT FROM ROUTINE 
Registers 

RO 

Rl 

R2 

Fields 


IDB$L_ OWNER 


CRBSV_BSY 


OPERATING SYSTEM ROUTINES 


Contents 
Destroyed 
Destroyed 
Destroyed 
Contents 


Clear (if no driver is waiting for’ the 
channel) 


Clear (if no driver is waiting for the 
channel) 


IPL at exit: caller's IPL 


IOCSRELDATAP in module IOSUBNPAG 


Driver fork processes call this routine to release a UNIBUS adapter 


buffered data path. 


This routine performs no operation if a data path 


is permanently allocated to the controller. If the data path wait 


queue contains waiting 


fork processes, it dequeuveS ae process, 


allocates the data path to that process, restores R3 through R5, and 
reactivates the suspended process. This routine should not be called 
unless the driver owns a buffered data path. 


INPUT TO ROUTINE 
Registers 

R5 

Fields 

UCBSL_CRB 
CRBSL_INTD+VECSL ADP 


CRBSL_INTD+ 
VECSB_DATAPATH 


VECSV_PATHLOCK 


ADPSL_DPOQFL 


Contents 

Address of unit control block 

Contents 

Address of the channel request block 

Address of the adapter control block 

Data path specifier 

Set to 1 to indicate that the data path is 
permanently allocated to the controller 


Head of the adapter data path wait queue 


IPL at execution: caller's IPL 


If the bit map is corrupted, this routine signals a  bugcheck with 
message code INCONSTATE. After IOCSRELDATAP completes successfully, 
it exits with an RSB instruction, 


OUTPUT FROM ROUTINE 
Registers 

RO 

Rl 

R2 

Fields 
ADPSW_DPBITMAP 

bits 0 through 4 


(in CRBSL INTD+ 
VECSB_DATAPATH) 


OPERATING SYSTEM ROUTINES 


Contents 
Destroyed 
Destroyed 
Destroyed 
Contents 
Data path is set to free if not allocated to 


another driver fork process 


Clear 


IPL at exit: caller's IPL 


IOCSRELMAPREG in module IOSUBNPAG 


Driver fork processes call this routine to release a set of UNIBUS 


adapter map registers. 


This routine performs no operation if map 


registers are permanently allocated to the controller. If the map 


register wait queue 


contains waiting fork processes, it dequeues a 


process and attempts to allocate the required set of map _ registers. 
If successful, it restores R3 through R5 and reactivates the suspended 
process. If not successful, it reinserts the fork process in the map 


register wait queue 


and dequeues the next process. This routine 


assumes that the caller is the current owner of the controller data 


channel. 


INPUT TO ROUTINE 
Registers 

R5 

Fields 

UCBSL_CRB 
VECS$V_MAPLOCX 

(in CRBSL_ INTD+ 
VECSW_MAPREG) 
CRBSL_INTD+VECS$L_ ADP 


CRBSL_INTD+ 
VECSW_MAPREG 


CRBSL_INTD+ 
VECSB_NUMREG 


ADPSL_ MRQFL 


Contents 

Address of unit control block 

Contents 

Address of the CRB 

If set, indicates that map registers are 
permanently allocated to the controller 
Address of the adapter control block 


Number of the starting map register 


Number of map registers to release 


Head of the queue of waiting drivers 


IPL at execution: caller's IPL 


IOCSRELMAPREG calls IOCSALTUBAMAP and IOCSALOUBAMAP. It exits with an 


RSB instruction. 


OPERATING SYSTEM ROUTINES 


OUTPUT FROM ROUTINE 


Registers Contents 
RO Destroyed 
Rl Destroyed 
R2 Destroyed 
Fields Contents 
ADPSW_MRBITMAP Map registers set to free 


IPL at exit: caller's IPL 


IOCSRELSCHAN in module IOSUBNPAG 


This routine releases a secondary controller's data channel; that is, 
the MBA controller data channel. For more information, refer to 
Appendix F. 


This routine has the same inputs and outputs as IOCSRELCHAN. 


IOCSREQCOM in module IOSUBNPAG 


Driver fork processes call this routine after a device I/0 operation 
and all device-dependent processing of an I/O request are complete. 
This routine writes RO and Rl into the I/0 request packet’ status 
field. It then inserts the I/O request packet into the [/0 
postprocessing queue. If error logging is occurring, it writes’ final 
status into the error message buffer and calls ERLSRELEASEMB. If the 
I/O request packet wait queue contains entries, it dequeues an I/O 
request packet and calls IOCSINITIATE. Otherwise, it clears a unit 
control block busy status bit to indicate that the device is idle. 


INPUT TO ROUTINE 


Registers Contents 

RO First longword of I/O status 

Rl Second longword of I/O status 

R5 Address of unit control block 

Fields Contents 

UCBSV_ERLOGIP Set or clear. Determines whether error 
(in UCBSW_STS) logging should be performed 

UCBSW_STS Final device status 

UCBSB_ERTCNT Final error counters 





Address of the error log message buffer 
















IPL at execution: caller's IPL 


OPERATING SYSTEM ROUTINES 


This routine places the I/O request packet in the queue headed by 
IOCSGL_PSBL. If UCBSL IOQEL has a packet queued to it, IOCSREOCOM 
sends the packet to IOCSINITIATE. This routine exits by branching to 
IOCSRELCHAN. 


OUTPUT FROM ROUTINE 


Registers Contents 
R2 Destroyed 
R3 Destroyed 


If IOCSINITIATE is called, other registers will be destroyed. 


Fields Contents 

IRPSL MEDIA I/O status (RO) 

IRP$L_MEDIA+4 I/O status (R1) 

EMBSQ_IOSB I/O status (RO and R1) 

UCBSL_OPCNT Incremented by 1 

EMB$B_ERTCNT UCB$B_ERTCNT 

EMBSB_ERTCNT+1 UCBSB_ERRCNT 

EMBSW_DV_STS UCBSW_STS 

UCBSV_BSY Clear (if no more packets in queue) 


(in UCBSW_STS) 


IPL at exit: caller's IPL 


IOCSREQDATAP (NW) in module IOSUBNPAG 


Driver fork processes call this routine to request a UNIBUS' adapter 
buffered data path for a DMA transfer. This routine performs no 
operation if a data path is permanently allocated to the controller. 
This routine locates a free data path and writes the data path number 
in the CRB. If no data paths are free, it saves R3 and R4 in the’ UCB 
fork block, inserts the fork block address in a data path wait queue, 
and suspends the driver fork process. 


INPUT TO ROUTINE 


Register Contents 

R5 Address of unit control block 

0 (SP) Caller's return address 

4(SP) Return address of the caller's caller 


OPERATING SYSTEM ROUTINES 


Fields Contents 

UCBSL CRB Address of the channel request block 
VECSV_PATHLOCK If set, indicates that the data path already 
(in CRBSL_INTD+ is allocated 

VECSB_ DATAPATH) 

CRBSL_INTD+VECSL ADP Address of the adapter control block 
ADPSW_DPBITMAP Indicates what data paths are available 


IPL at execution: caller's IPL 


If IOCSREQDATAP cannot allocate a data path, and NW is not’ specified, 
the routine saves process context by placing the contents of R3, R4 
and the PC in the UCB fork block and placing R5 in the data path wait 
queue (ADPSL DPQBL). If, however, NW is specified, the routine does 
not suspend the process to wait for the data path. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SSS NORMAL (success) 
QO (failure) 

Fields Contents 

CRBSL_INTD+ Data path number 


VECSB_DATAPATH 
ADPSW_DPBITMAP Bit for allocated data path clear 


IPL at exit: caller's IPL 


IOCSREQMAPREG in module IOSUBNPAG 


Driver fork processes call this routine to request a set of UNIBUS 
adapter map registers for a DMA transfer. This routine performs no 
operation if map registers are permanently allocated to the 
controller. This routine locates the required number of map registers 
and writes the number of registers and the number of the _ first 
register into the CRB. If sufficient map registers are not available, 
it saves R3 and R4 in the UCB’ fork block, inserts the fork block 
address in a map register wait queue, and suspends the driver fork 
process. 


INPUT TO ROUTINE 


Registers Contents 

R5 Address of unit control block 

0 (SP) Return address of caller 

4(SP) Return address of the caller's caller 


OPERATING SYSTEM ROUTINES 


Fields Contents 

UCBSW_BCNT Transfer byte count 

UCBSW_BOFF Byte offset into page of start of buffer 
UCBSL_ CRB Address of CRB 

CRBSL_INTD+ Address of the adapter. control block 
VECSL_ADP | 

VECSV MAPLOCK Determines status of map lock bit 


(in CRBSL_INTD+ 
VECSW_MAPREG) 


ADPSW_MRBITMAP Adapter map register allocation bit map 
IPL at execution: caller's IPL 


If registers are not available, this routine suspends the process by 
Saving the following context: 


e R3 and R4 are saved in UCBSL FR3 and UCBSL FR4, respectively. 
e PC is saved in UCBSL FPC. 
e R5 is saved in ADPSL_MROBL, which is the adapter's map 


register wait queue. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO SSS NORMAL (success) 

Rl Destroyed 

R2 Destroyed 

Fields Contents 

CRBSL_INTD+ Starting map register number of those 
VECSW_MAPREG allocated 

CRBSL INTD+ Number of map registers allocated 


VECSB_NUMREG 
ADPSW_MRBITMAP Allocated map registers 


IPL after execution: caller's IPL 


IOCSREQPCHANH in IOSUBNPAG.MAR 


Driver fork processes call this routine to request a channel on _ the 


primary controller with high priority. If the controller data channel 
is idle, this routine writes the UCB address in the interrupt data 


block and returns the CSR address in R4. Otherwise, it saves R3 in 
the UCB fork block, inserts the fork block address at the front of the 
channel wait queue, and suspends the driver fork process. 


OPERATING SYSTEM ROUTINES 


INPUT TO ROUTINE 


Registers Contents 

R5 Address of unit control block 

0(SP) Return address of the caller 

4(SP) Return address of the caller's caller 

Fields Contents 

UCBSL CRB Address of the channel request block 

CRBSL_ LINK Address of the secondary channel request 
block 

CRBSL_INTD+VECSL_ IDB Interrupt data block address 

CRBSV_BSY Set or clear. If set, indicates that the 

in CRBSB_ MASK channel is busy 

IDBSL CSR Address of device CSR 


IPL at execution: caller's IPL 


If the channel is busy, this routine saves driver context by storing 


the contents of R3 and R4 in UCBSL FR3 and UCBSL FR4, respectively, 
storing 0(SP) in UCBSL FPC and placing the contents of R5 in the CRB 
wait queue (CRBSW _WOQFL). 


IOLSREQPCHANH exits by issuing an RSB instruction. 


OUTPUT FROM ROUTINE 


Registers Contents 

RO Destroyed 
Rl Destroyed 
R2 Destroyed 
R4 IDBSL_CBR 
Fields Contents 

IDBSL_ OWNER R5 


IPL at exit: caller's IPL 


IOCSREQPCHANL in module IOSUBNPAG 


Driver fork processes call this routine to request a channel on the 
primary controller with low priority. This routine performs in the 
Same manner as IDLSREQPCHANH, except that, should driver have to wait 
for the channel, IOCSREQPCHANL places the UCB at the end of the 
channel wait queue. | 
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OPERATING SYSTEM ROUTINES 


IOCSREQSCHANH in module IOSUBNPAG 


Driver fork processes call this routine to request a channel on _ the 
secondary controller with high priority. 


The input to and output from this routine are the same as_ for 


IOCSREQPCHANH, except that the secondary controller data channel is 
assigned. 


IOCSREQSCHANL in module IOSUBNPAG 


Driver fork processes call this routine to request a channel on the 
secondary controller with low priority. 


The input to and output from this routine are the same as_ for 


IOCSREQPCHANH, except that the secondary controller data channel is 
asSigned. 


IOCSRETURN in module IOSUBNPAG 


This routine merely returns by issuing an RSB instruction. It has no 
input requirements and produces no output. 


IOCSWFIKPCH in module IOSUBNPAG 


Driver fork processes call this routine to suspend driver processing 
to wait for an interrupt or device timeout and still retain the 
controller data channel. This routine saves R3, R4, and the driver's 
return PC from top of stack in the UCB fork block. It sets UCB bits 
to indicate that an interrupt or a timeout is expected and sets’ the 
timeout time in the unit control block. It clears the UCB bit that 
indicates that the unit is timed out and lowers IPL back to the IPL 
saved on top of stack. Then, it returns to the caller of the driver 
fork process. | 


The two bytes following the JSB to IOCSWFIKPCH contain the relative 
offset to the timeout routine. 


INPUT TO ROUTINE 


Register Contents 

R5 Address of unit control block 

0(SP) Address following the JSB to IOCSWFIKPCH 

4 (SP) Timeout value in seconds 

8 (SP) IPL to which to lower before returning to the 
caller's caller 

12 (SP) Return address of the caller's caller 

Field Contents 

EXESGL ABSTIM Absolute time. Used to compute time at which 


device times out 


IPL at execution: Fork a device IPL (caller's IPL) 
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OPERATING SYSTEM ROUTINES 


This routine removes 0(SP) through 11(SP) from the stack explicitly 
and 12(SP) through 15(SP) implicitly by exiting with an _ RSB 
instruction, which returns to the caller's caller. 


OUTPUT FROM ROUTINE 


Registers Contents 

Fields Contents 

UCBSL DUETIM Sum of timeout value and EXESGL ABSTIM 

UCBSV_INT Set to indicate that interrupts are expected 
on the device 

UCBSV_TIM Set to indicate that timeouts are expected on 
the device 

UCBSV_TIMOUT Cleared to indicate that unit is not timed 
out 

UCBSL_ FR3 R3 

UCBSL_FR4 R4 

UCBSFPC 0(SP)+2 


IPL at exit: IPL specified in 8(SP) 


IOCSWFIRLCH in IOSUBNPAG 


Driver fork processes call this routine to suspend driver processing 


to wait for an interrupt or device timeout first releasing the 
controller data channel. 


The input to and output from this routine are the same as IOCSWFIKPCH 


except that IOCSWFIRLCH exits to IOCSRELCHAN, which releases the 
controller dates channel. 


APPENDIX D 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


This appendix contains the source listing of a driver for an 
analog-to-digital converter. 
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SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


-TITLE ADDRIVER ~ VAX/VMS AD11-K DRIVER 
-IDENT ‘'v02~-000! 
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++ 


Copyright (c) 1978,1979,1980 
by DIGITAL Equipment Corporation, Maynard, Mass. 


This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 


The information in this software is subject to change without notice 


and should not be construed as a commitment by DIGITAL Equipment 
Corporation. 


DIGITAL assumes no responsibility for the use or reliahility of its 
software on equipment which is not Supplied by DIGITAL. 
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FACILITY: 


VAX/VMS AD11-K I/O DRIVER 


ABSTRACT : 


DEVICE TABLES AND DRIVER CODE FOR THE AD11-K ANALOGUE 
TO DIGITAL CONVERTER WITH OPTIONAL AMI1-K MULTIPLEXER. 


AUTHOR: 


S. PROGRAMMER, SEPTEMBER 1978. 
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SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


~SBTTL FUNCTIONAL DESCRIPTION OF DRIVER 


THE DRIVER SUPPORTS A/D SAMPLING ON GROUPS OF CHANNELS VIA QIO 

READ REQUESTS. NO EXTERNALLY TRIGGERED SAMPLING (I.E., CLOCK 
OVERFLOW OR SCHMITT TRIGGER) IS SUPPORTED. THE AM11-K MULTIPLEXER 
MAY BE PRESENT, BUT NO AUTOMATIC RANGING AMPLIFICATION I5 

DONE AT DRIVER LEVEL. THE BUILT-IN DAC MAY BE USED FOR. TESTING VIA 
A LOOPBACK QIO FUNCTION DEFINED ESPECIALLY FOR THIS DEVICE. 


THE QIO FUNCTIONS AVAILABLE ARE: 


IO$_READVBLK -READ VIRTUAL BLOCK 
IO$ READLBLK -READ LOGICAL BLOCK 
I0$ READPBLK -READ PHYSICAL BLOCK=IOS$_ LOOPBACK 
IO0$_ LOOPBACK “WRITE DAC, READ RESULTS; REQUIRES 


PHYSICAL I/O PRIVILEGE 
THE STANDARD QIO PARAMETERS ARE: 


P1=BUFFER ADDRESS 

P2=BUFFER BYTE COUNT 

P3=SPECIFIER OF CHANNELS TO SAMPLE: 
BIT O-7/INITIAL CHANNEL # (0-63) 
BIT 8-15/TOTAL # OF CHANNELS TO SAMPLE (1-64) 
BIT 16-23/CHANNEL INCREMENT (0-63) 
BIT 24-31/IGNORED 

P4=DAC VALUE, USED FOR LOOPBACK ONLY: 
BIT 0-7/8 BIT DAC VALUE 
BIT 8-31/IGNORED 

P5,P6 ARE NOT USED 


IN ADDITION TO THE STANDARD STATUS CODES THAT CAN BE RETURNED FOR 
A QIO, THE FOLLOWING DEVICE-SPECIFIC I/O STATUS VALUES ARE DEFINED: 


SS$_DATAOVERUN -ERROR BIT SET IN CSR; SAMPLING ABORTED 

WITH LAST GOOD SAMPLE IN BUFFER 
SSS BADPARAM -INVALID CHANNEL SPECIFIER; NO SAMPLES TAKEN 
SS$_BUFFEROVF -USER BUFFER OVERRUN; AS MANY CHANNELS AS WILL 


FIT ARE SAMPLED 


THE SAMPLES ARE RETURNED IN THE CALLER'S BUFFER PACKED ONE SAMPLE 
PER WORD, BITS O-1ll. THE BYTE COUNT RETURNED IN THE SECOND WORD OF 


THE I/O STATUS BLOCK ALWAYS REFLECTS THE # OF BYTES ACTUALLY FILLED 
WITH SAMPLE DATA. THE NUMBER OF SAMPLES IS ONE HALF THE RETURNED 


BYTE COUNT. 


EXAMPLE: SWEEP THROUGH 32 INPUTS CONNECTED IN DIFFERENTIAL MODE 
(ADL1-K AND AM11-K): 


SWEEPBUF: ~-BLKW 32 
NUMINPUT: ~ LONG 32 
CHANSPEC: BYTE 0,32,2 ;START WITH CHANNEL 0; 


; SAMPLE CHANNELS 0,2,4,...,52 


S$QIO_S CHAN=X,FUNC=I0$ READVBLK ,- 
P1=SWEEPBUF , P2=NUMINPUT, P3=CHANSPEC 
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SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


~-SBTTL MACRO LIBRARY CALLS 


EXTERNAL SYMBOLS (LIB/LIB): 


SCRBDEF *>CHANNEL REQUEST BLOCK 
SDDBDEF *>DEVICE DATA BLOCK 
SIDBDEF s INTERRUPT DATA BLOCK 
SIODEF *I/O FUNCTION CODES 
SIPLDEF | s>HARDWARE IP DEFINITIONS 
SIRPDEF ;I/O REQUEST PACKET 
SUCBDEF sUNIT CONTROL BLOCK 
SVECDEF ; INTERRUPT VECTOR BLOCK 
SJIBDEF ;JOB INFORMATION BLOCK 


USER DEFINED EXTERNAL SYMBOLS ARE CONTAINED IN A USER LIBRARY . 

THE CONTENTS OF THIS LIBRARY CAN BE MERGED WITH THE SYSTEM LIBRARY 
TO ALLOW USER PROGRAMS TO USE EXTENDED FUNCTION CODES WITHOUT HAVING 
TO DEFINE THEM LOCALLY. 

THIS DRIVER MUST BE ASSEMBLED WITH A USER LIBRARY TO DEFINE SXIODEF. 


SXIODEF ;EXTENDED QIO FUNCTIONS.THIS MACRO 
;CONTAINS THE DEFINITIONS FOR 
;10$ LOOPBACK 
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SAMPLE DRIVER FOR AN 


-SBTTL LOCAL DEFINITIONS 


LOCAL DEFINITIONS: 


QIO ARGUMENT LIST OFFSETS: 


P1=0 
P2=4 
P3=8 
P4=12 
P5=16 
P6=20 
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DEVICE PARAMETERS: 


DAC_TIMER=20 
MAX_INLCHN=63 
MAX_NUMCHN=64 
MAX_INCCHN=63 
ADC_TIMER=2 
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SDEF 


SDEF 


SDEF 
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DEVICE REGISTER DEFINITIONS: 


SDEFINI AD 


AD CSR .BLKW 1 
VIELD AD _CSR,0,<- 

<GO,,M>,- 

<,3>—- 

<EXT, ,M>,- 
<COV,,M>,- 
<IE,,M>,- 

<DON, »M>,- 
<MUX,6,M>,- 

<,1l>,- 

<ERR, ,M>,- 

> 

AD DBR .BLKW 1 

=.-2 

AD DAC .BLKW 1 


SDEFEND AD 
DEVICE DEPENDENT UCB EXTENSIONS: 


SDEFINI UCB 


.=UCBSK_LENGTH 


SDEF UCB$B_AD CURCHN .BLKB_ 1 
SDEF UCBSB AD NUMCHN .BLKB-~ 1 
S DEF UCBSB_ AD INCCHN .BLKB_ 1 

~BLKB 1 
$DEF UCBSW_AD_CSR -BLKW 1 


A-TO-D CONVERTER 


;FIRST, 
SECOND, 

THIRD, 

FOURTH, 

FIFTH, 

AND SIXTH PARAMETERS 


™=e ue “OS 
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720 USEC TIMER FOR DAC SETTLE 
;MAXIMUM INITIAL CHANNEL #, 

; NUMBER OF CHANNELS, 

; AND CHANNEL INCREMENT 

;A/D CONVERSION TIMEOUT=2 SEC 


;CONTROL/STATUS REGISTER 


;DEFINE CSR FIELDS: AD CSR M_XXX 
> START A/D CONVERSION ~ 

» 3 UNUSED BITS 

> EXTERNAL START ENABLE 

> CLOCK OVERFLOW ENABLE 

> INTERRUPT ENABLE 

> CONVERSION DONE FLAG 

> 6 BIT MUX CHANNEL # 

> BIT 14 IS UNUSED 

: ERROR FLAG 

*END OF CSR FIELDS 

A/D DATA BUFFER REGISTER 

> DATA BUFF REG=DAC BUFF REG 
>DAC DATA BUFFER REF 


;END OF A/D REGISTER DEFNS 


;STEP TO END OF STANDARD UCB 
;NOTE: NEXT 4 BYTES ASSUMED 
; ADJACENT 

;CURRENT MUX CHANNEL # 

;# CHANNELS LEFT TO SAMPLE 
;CHANNEL INCREMENT 

;SPARE BYTE 

;SAVED CSR 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


_VIELD UCBSW_CSR,1,<- ;BORROW UNUSED CSR BIT 
<BFO,,M>,- ; FOR USER BUFFER OVERRUN 
> 

UCBSK_ADLENGTH=. ;LENGTH OF A/D UCB 
SDEFEND UCB ;END OF UCB EXTENSIONS 


e 
f 


; A/D DRIVER USE OF TEMPORARY IRP STORAGE: 


IRPSL CHSPEC=IRPSL MEDIA ;CHANNEL SPECIFIER(P3) 
IRPSL DACVAL=IRPSL_ MEDIA+4 ;OPTIONAL DAC VALUE(P4) 


a 


e 
é 
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SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


-SBTTL DRIVER PROLOGUE AND DISPATCH TABLES 


DRIVER PROLOGUE TABLE: 


DPTAB = 


END=AD_END,- 
ADAPTER=UBA,- 


;DEFINE DRIVER PROLOGUF TABLE? 
END OF DRIVER, 
UNIBUS ADAPTER 


: 
UCBSIZE= NCRSK _ADLENGTH,-; SIZE OF A/D UCB, 
; 


NAME=ADDRIVER | 


DPT_STORE 
DPT STORE 
DPT STORE 
DPT STORE 


DPT_STORE 
DPT STORE 


DPT_STORE 
DPT_STORE 


DPT STORE 


DPT STORE 


DRIVER DISPATCH TABLE: 


DRIVER NAME 


; 
INIT ; VALUES TO BE SET ON LOAD 


UCB,UCBSB FIPL,B,8 >DEVICE FORK IPL 
UCB,UCBS$B DIPL,B,22 ;AD11 HARDWARE IPL 

UCB,UCBSL DEVCHAR,L,- >AD11 DEVICE CHARACTERISTICS: 
<DEVSM AVL- > AVALILABLE, 

!DEVSM IDV- ; INPUT DEVICE, 

!DEVSM_RTM> ; REALTIME DEVICE 

REINIT *VALUES TO SFT ON RELOAD 
CRB,CRBSL INTD+4, D,- ; INTERRUPT SERVICE ADDR 

AD_ INTERRUPT 

CRB,- sADDR OF CONTROLLER 


CRBSL INTD+VECSL _INITIAL ,- ; INITIALIZATION 
I), AD _CTLINIT 


CRB,- ;ADDR OF UNIT 

CRBSL INTD+VECSL_ UNITINIT,-— ; INITIALIZATION 
D,AD UNITINIT 

DDB, DDBSL_ DDT ,D,- ;ADDR OF DRIVER 
ADSDDT DISPATCH TABLE 


e 
? 
° 
’ 
e 
‘ 


END END DRIVER PROLOGUE 


DDTAB = ;DDT CREATION MACRO 
DEVNAM=AD ,- ;NAME OF DEVICE 
START=AD_STARTIO,- ;ADDR OF START I/O ROUTINE 
FUNCTB=AD_ FUNCTABLE ;ADDR OF FDT 


~SBTTL 


AD11 FUNCTION 


=e "&e Oe 


AD_FUNCTABLE: 
FUNCTAB 


FUNCTAB 


FUNCTAB 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


AD11-K FUNCTION DECISION TABLE 


DECISION TABLE: 


;FUNCTION DECISION TABLE START 
1 ; LEGAL FUNCTIONS: 


<LOOPBACK ,- ; LOOPBACK READ FROM DAC 
READPBLK ,- ; READ PHYSICAL BLOCK 
READLBLK ,- ; READ LOGICAL BLOCK 
READVBLK> ; READ VIRTUAL BLOCK 

,7 ;BUFFERED I/O FUNCTIONS: 
<LOOPBACK ,- ; LOOPBACK READ FROM DAC 
READPBLK ,- ; READ PHYSICAL BLOCK 
READLBLK ,- ; READ LOGICAL BLOCK 
READVBLK> ; READ VIRTUAL BLOCK 

= ;PREPROCESSING ROUTINES: 
AD READ ,- ;CALL SINGLE PREPROCESSOR FOR: 
<LOOPBACK ,- ; LOOPBACK READ FROM DAC 
READPBLK ,- ; READ PHYSICAL BLOCK 
READLBLK ,- ; READ LOGICAL BLOCK 
READVBLK> ; AND READ VIRTUAL BLOCK 


me 
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SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


~SBTTL AD_READ: READ FUNCTION PROCESSING 
AD_READ - READ FUNCTION PREPROCESSING 


THIS ROUTINE IS CALLED FROM THE FUNCTION DECISION TABLE DISPATCHER 
TO PROCESS A READ PHYSICAL, READ LOGICAL, READ VIRTUAL, OR LOOPBACK 
I/O FUNCTION. 


AD_READ FIRST VERIFIES THE CALLER'S PARAMETERS, TERMINATING THE 
REQUEST WITH IMMEDIATE SUCCESS OR ERROR IF NECESSARY. P3 AND 

P4 ARE STORED IN THE IRP. A SYSTEM BUFFER IS ALLOCATED AND 

ITS ADDRESS IS SAVED IN THE IRP. THE CALLER'S QUOTA IS UPDATED, 
AND THE READ REQUEST IS QUEUED TO THE DRIVER FOR STARTUP. 


INPUTS: 


RO,R1,R2 = SCRATCH 
R3 = IRP ADDRESS 


R4 = ADDR OF PCB FOR CURRENT PROCESS 
R5 = DEVICE UCB ADDRESS 

R6 = ADDRESS OF CCB 

R7 = I/O FUNCTION CODE 


R8 = FDT DISPATCH ADDR 
R9-R11 = SCRATCH 


AP = ADDR OF FUNCTION PARAMETER LIST 
OUTPUTS: 


RO,R1,R2 = DESTROYED 

R3-R11,AP = PRESERVED 

IRPSL_ CHSPEC(R3) = CHANNEL SPECIFIER (P3) 

IRPSL DACVAL(R3) = OPTIONAL DAC VALUE (P4) 
IRP$L_SVAPTE(R3) = ADDR OF ALLOCATED SYSTEM BUFFER 
IRP$W_BOFF(R3) = REQUESTED BYTE COUNT 


SYSTEM BUFFER: 
LONGWD O/ADDR OF START OF DATA=BUFF ADDR+12 
LONGWD 1/ADDR OF USER BUFFER 
LONGWD 2/DATA STRUCTURE BOOKKEEPING 


~ENABL LSB 


AD_READ: >READ FUNCTION PREPROCESSING 
MOVZWL P2(AP) ,R1 >GET USER BYTE COUNT 
BEQL 10$ >BRANCH IF READ OF 0 BYTES 
> (=INSTANT SUCCESS) 
MOVZWL #SS$_BADPARAM,RO >ASSUME CHANNEL SPEC ERROR 
MOVAL P3(AP) ,R2 >GET ADDR OF CHANNEL SPEC 
CMPB (R2)+,#MAX INLCHN >INITIAL CHAN # TOO LARGE? 
BGTRU 20$ - >BRANCH IF SO 
TSTB (R2) ># CHANNELS = 0? 
BEQL 10$ *BRANCH IF SO (SUCCESS) 
CMPB (R2)+,#MAX NUMCHN ># CHANNELS TO SAMPLE TOO LARGE? 
BGTRU 20$ > >BRANCH IF SO 
CMPB (R2) ,#MAX_INCCHN >CHANNEL INCREMENT TOO LARGE? 
BGTRU 20S >BRANCH IF SO 
MOVQ P3(AP),IRPSL CHSPEC(R3) ;STORE P3 AND P4 (OPTIONAL DAC) 
> IN IRP UNTIL REQUEST EXECUTION 
MOVL P1 (AP) ,RO *GET ADDR OF USER BUFFER 
JSB G*EXESREADCHK *VERIFY THAT CALLER HAS 
> WRITE ACCESS TO BUFFER 
PUSHR #~M<RO,R3> *>SAVE USER BUFF ADDR, IRP ADDR 
ADDL #12,R1 sADD 12 BYTES TO REQUESTED BUFF 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


JSB G”“ EXESBUFFRQUOTA 
BLBC RO ,30$ 

JSB G”“ EXESALLOCBUF 
BLBC RO,30$ 

POPR #“M<RO,R3> 

MOVL R2,IRPSL_SVAPTE(R3) 
MOVW Rl1,IRPSW_BOFF (R3) 
MOVZWL R1,R1 

MOVL PCBSL JIB(R4) ,R4 
SUBL Rl1,JIBSL_BYTCNT(R4) 
MOVAB 12(R2) , (R2)+ 

MOVL RO, (R2) 

JMP G”“EXESQIODRVPKT 


; COME HERE IF USER REQUESTED READ OF 0 
; THIS IS ALWAYS SUCCESSFUL AND DOES NO 


10S: 
20S: 


MOV ZWL 
JMP 


#SSS$_NORMAL ,RO 
G*EXES$FINISHIOC 


=e “=p %e 


308: POPR #“M<R2,R3> 
JMP G“EXESABORTIO 
-DSABL LSB 


D-10 


; SIZE FOR BUFF HEADER 

;VERIFY BUFFER SPACE LEFT 

; IN CALLER'S QUOTA 

;BRANCH IF INSUFFICIENT QUOTA 

; ALLOCATE A SYSTEM BUFFER 
;BRANCH IF NONE AVAILABLE 
;RESTORE USER BUFFER, IRP ADDR 
;SAVE ADDR OF SYSTEM BUFFER 

; AND REQUESTED BYTE COUNT 
;CONVERT TO LONGWORD 

;GET JOB INFORMATION BLOCK ADDRESS 
;DEDUCT REQUESTED BYTE COUNT 

; FROM PROCESS! QUOTA 

;SAVE ADDR OF START OF USER DATA 
; IN 1ST LONGWD OF SYSTEM BUFFER 
;SAVE USER BUFFER ADDR IN 

; 2ND LONGWD 

;QUEUE I/O PKT TO DRIVER 


BYTES OR O CHANNELS. 
DEVICE I/0: 


;SET NORMAL COMPLETION STATUS 
;COMPLETE I/O REQUEST 


COME HERE TO ABORT I/O REQUEST WITH EXCEPTION STATUS IN RO: 


;CLEAR BUFFER ADDR; RESTORE IRP 
; ADDR 
;COMPLETE I/O REQUEST 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


e-SBTTL AD STARTIO: PERFORM A/D CONVERSIONS 


AD_STARTIO - START I/O OPERATION ON AD11-K A/D CONVERTER. 


=e oe 


THIS ROUTINE IS ENTERED WHEN THE ASSOCIATED UNIT IS IDLE AND A 
PACKET IS AVAILABLE FOR PROCESSING. 


TO PREPARE FOR SAMPLING, AD _STARTIO PERFORMS THESE STEPS: 


1. SET UP UCB WITH CHANNEL SPECIFIER AND ADDRESS IN SYSTEM 
BUFFER TO HOLD FIRST SAMPLE. 

2. IF LOOPBACK WAS SPECIFIED, THE DAC IS SET WITH THE CALLER- 
SPECIFIED VALUE. 


=e ‘eo we NO “8 We Se We Ws Be We WE 


THE DRIVER THEN LOOPS FROM AD_NXTSAMPLE TO AD_ENDSAMPLE 
COLLECTING SAMPLES UNTIL ALL SAMPLES HAVE BEEN COLLECTED, 


OR AN ERROR OCCURS. AN INTERRUPT IS RECEIVED FOR EACH SAMPLE, 
BUT, TO SAVE TIME, THE DRIVER NEVER FORKS UNTIL TIME TO 


COMPLETE THE I/O REQUEST. 


=e 


=e “eB 
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INPUTS: 

R3 = ADDR OF IRP 

R5 = ADDR OF DEVICE UNIT UCB 
OUTPUTS: 


RO,R1,R2 = DESTROYED 
OTHER REGISTERS ARE PRESERVED 


me we Se Se We BO We We 


e-ENABL LSB 


AD STARTIO: ;START NEXT QIO 
MOVL IRPSL_CHSPEC(R3) ,- ;COPY CHANNEL SPEC FROM 
UCBS$B AD CURCHN(R5) ; IRP TO UCB 
MOVL @IRPSL_ SVAPTE(R3) ,- ;SET ADDR OF START DATA 
UCBSL_SVAPTE(R5) ; IN UCB 
MOVL UCBSL_ CRB(R5) ,R4 ;GET CRB ADDRESS, 
MOVL @CRBSL_INTD+VECSL_IDB(R4),R4 ; THEN CSR ADDRESS 
BICB3 #°C<IOSM FCODE>,- ;GET THE I/0 
IRPSW_FUNC(R3) ,RO ; FUNCTION CODE 
CMPB RO,#I0$ LOOPBACK ; LOOPBACK? 
BNEQ AD_NXTSAMPLE ;BRANCH IF NOT 
MOVZBW IRPSL DACVAL(R3) ,- ;SET DAC VALUE IN 
AD DAC (R4) ; DAC BUFFER REGISTER 
MFPR S°#PRS_ICR,R1 ;GET CURRENT INTERVAL COUNTER (USEC) 
ADDL #DAC_TIMER,R1 ; +DAC SETTLE TIME IN USEC 
BLSS 10$ ;BRANCH IF COUNTER DOESN'T 
; OVERFLOW 
MOVAW -10000(R1),R1 ;ELSE CALCULATE COUNTER 
; FOR NEXT INTERVAL 
10$: MFPR S°#PRS$_ICR,RO ;READ INTERVAL COUNTER NOW 
CMPL RO,R1 | >REACHED SETTLE TIME YET? 
BLSS 10$ ;BRANCH IF NOT 
AD_NXTSAMPLE: ;START NEXT SAMPLE 


MOVZBW #AD_CSR_M IE!AD CSR_M GO,RO ;SET INTERRUPT ENABLE AND 
; START A/D CONVERSION 


INSV UCB$B_AD CURCHN(RS),-  ;SET MUX CHAN # 

#8,#6,RO ; FOR CSR 
DSBINT »DISABLE INTERRUPTS (IPL=IPLSPOWER) 
BBSC #UCBSV POWER,- >BRANCH IF POWER FAILURE 


UCBSW_STS(R5) ,AD_POWERFAIL ; AND CLEAR POWER FAIL SIGNAL 


MOVW 
WFIKPCH 
MOVW 
BLSS 
MOVW 


ADDL 
SUBL 
DECB 
BEQL 
CMPW 
BLSSU 
BICW 


ADDB 

BICB 
AD _ ENDSAMPLE: 

BRB 


- DSABL 


SAMPLE DRIVER FOR AN A~-TO-D CONVERTER 


RO,AD CSR(R4) 


AD_TIMEOUT,#ADC_ TIMER 


;SET CSR 
;WAIT FOR INTERRUPT, OR TIMEOUT 


AD CSR(R4) ,UCBSW AD CSR(R5) ; SAVE CSR IN UCB 


AD CSRERROR 


; BRANCH IF ERROR 


AD DBR(R4) ,@UCBSL_SVAPTE(R5) ;COPY A/D VALUE INTO 


#2,UCBSL_SVAPTE(R5) 
#2,UCBSW_BCNT(R5) 
UCBSB_AD_ NUMCHN(R5) 
AD_DONE 
UCBSW_BCNT(R5) , #2 
AD_BUFFEROVF 
#UCBSW_CSR_M_BFO,- 
UCBSW_AD_CSR(R5) 


UCBSB_ AD INCCHN(RS) ,- 


UCBSB AD CURCHN(R5) 
#°“C<MAX NUMCHN-1>,- 


UCB$B_ AD CURCHN(R5) 


AD_NXTSAMPLE 


LSB 


; SYSTEM BUFFER 

;STEP BUFFER POINTER 

;DECREASE # BYTES LEFT IN REQUEST 
;DECR # CHANNELS LEFT TO SAMPLE 
;BRANCH IF NONE 

;AT LEAST 2 BYTES LEFT IN BUFFER? 
;BRANCH IF NOT 

;ELSE CLEAR BUFFER OVERRUN 

; BIT IN CSR COPY 

;NEXT CHANNEL # = 

; CURRENT CHANNEL+INCREMENT 

+ MODULO MAXIMUM 

; CHANNEL # 


;THIS SAMPLE COMPLETE 
;GO START NEXT SAMPLE 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


~OBTTL - I/O REQUEST COMPLETION 


COME HERE TO COMPLETE I/O REQUEST WITH NORMAL OR ERROR STATUS. 


USER BUFFER OVERRUN, I.E., NO MORE SAMPLES CAN BE COLLECTED: 


=e Se OT! =e Wwe 


»~ENABL LSB 


AD _BUFFEROVF: 
BISW #UCBSW_CSR_M_ BFO,- ;SET BUFFER OVERRUN BIT 
UCBSW_AD_CSR(R5) ; IN CSR COPY 
; CSR ERROR BIT WAS SET: 


° 
? 


AD_CSRERROR: ; 
TSTW = AD_DBR(R4) ;CLEAR ERROR 
BRB AD DONE ;JOIN COMMON I/O COMPLETION 


DEVICE TIMED OUT DUE TO EITHER A REAL TIMEOUT OR TO A 
POWER FAILURE. BOTH CAUSES ARE HANDLED THE SAME. 


=e "es We Ve 


AD TIMEOUT: : 
CLRW AD_CSR(R4) *CLEAR INTERRUPT ENABLE, 
TSTW AD DBR(R4) > PENDING CONVERSION, INT, OR ERROR 
SETIPL UCB$B FIPL(RS) >LOWER PRIORITY TO DEVICE LEVEL 
BRB 10s — :JOIN COMMON CODE TO 


; TERMINATE REQUEST 


POWER FAILURE DETECTED WHILE ATTEMPTING TO INITIATE A READ OR 
LOOPBACK REQUEST. TERMINATE REQUEST THE SAME AS IF IT OCCURRED 
DURING THE QIO. 


“se “se Yo We RO 


AD POWERFAIL: ; 
ENBINT ; LOWER IPL BACK TO FORK IPL 


10S: MOV ZWL #SS$_TIMEOUT,RO ;SET STATUS TO TIMED OUT 
BRB 20$ ;JOIN COMMON CODE TO TERMINATE 
; REQUEST 


NORMAL STATUS, CANCEL I/0, AND GENERAL I/O REQUEST COMPLETION: 


=e Se “6 


AD DONE: ; 
= CLRW AD_CSR(R4) ;CLEAR INTERRUPT ENABLE 
IOFORK s;REQUEST RESUMPTION AS FORK PROCESS 
MOVZWL #SSS DATAOVERUN ,RO ; ASSUME CSR ERROR 
BBS #AD CSR _V_ERR,- ;BRANCH IF SO 
UCBSW AD CSR(R5) ,20$ ; 
MOVZWL #SS$_BUFFEROVF,RO ;ASSUME BUFFER OVERRUN 
BBS #UCBSW_CSR_V_BFO,- ;BRANCH IF SO 
UCBSW_AD_ CSR(R5) ,20$ : 
MOVZWL #SSS_ NORMAL ,RO ;ELSE, STATUS IS NORMAL 


20S: 


SUBW3 
INSV 
CLRL 
REQCOM 


« DSABL 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


UCBSW_BCNT(R5) ,- *GET # BYTES REQUESTED 

IRPSW BCNT(R3) ,R1 ; -# BYTES NOT XFERRED 
R1,#146,#16,RO0 ; =# BYTES XFERRED 

Rl ;CLEAR SECOND I/O STATUS LONGWD 


;REQUEST I/O COMPLETION 
LSB 


~SBTTL 


+ 


THIS ROUTINE I 


INPUTS: 


me we "08 “Se MO NO We Teo Be WH We 


ALL GENE 
SP/ INTE 
0 (SP) 

4(SP) 

8 (SP) 

12(SP) 
16 (SP) 
20(SP) 
24 (SP) 
28 (SP) 
32 (SP) 
IPL/ 


OUTPUTS AT CAL 
R3 = 
R4 = 


R5 = UCB 


me “e we “ee Se Se Te BO Be “SO We We Te WO We we We WE 
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» ENABL 


AD_INTERRUPT: 
MOVL 
MOVO 
BBCC 


MOVL 

JSB 
105% MOVQ 
MOVQ 
MOVQ 
REI 
AD_UNSOL: 

CLRW 


TSTW 
BRB 


~DSABL 


~SBTTL 
+ 


=e 


FAILURE. 
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LAST SAMPLE 


RESTORED FROM DRIVER 
RESTORED FROM DRIVER 


STACK IS SAME AS ABOVE, 
IPL/ HARDWARE DEVICE LEVEL 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


AD INTERRUPT: 


S ENTERED VIA A JSB 


INTERRUPT OCCURS ON AN AD11 A/D CONVERTER. 
GETS THE ADDRESS OF THE UCB OF THE INTERRUPTING DEVICE, 
THE REMAINING CONTEXT OF THE DRIVER FORK PROCESS WHICH INITIATED 
THE DEVICE ACTIVITY, AND CALLS THE DRIVER FORK PROCESS. 


RAL REGISTERS = RANDOM 
RRUPT STACK 

ADDR OF IDB ADDR 

SAVED RO 

SAVED Rl 

SAVED R2 

SAVED 
SAVED 
SAVED 
SAVED 


SAVED PSL 


HARDWARE DEVICE LEVEL 


L TO DRIVER FORK: 


ADDR 


LSB 


@(SP)+,R3 
IDB$L_CSR(R3) ,R4 
#UCBSV_INT,- 
UCBSW_STS(R5) ,AD_UNSOL 
UCBSL_FR3(R5) ,R3 


@UCBSL_FPC(R5) 


(SP)+,RO 
(SP)+,R2 
(SP)+,R4 


AD _CSR(R4) 
AD DBR(R4) 
10$ 


LSB 
AD CTLINIT: 


THE CSR IS CLEARED TO DISABLE INTERRUPTS. 
(IF ONE IS IN PROGRESS) TO TIME OUT IN CASE INITIALIZATION 


AD11-K CONTROLLER 


AD11-K A/D CONVERTER INTERRUPT SERVICE 
AD_INTERRUPT - A/D CONVERTER INTERRUPT SERVICE 


INSTRUCTION WHEN AN 


INTERRUPT SERVICE 
RESTORES 


FORK PROCESS (IRP ADDR) 
FORK PROCESS (CSR ADDR) 


BUT IDB POINTER POPPED 


;A/D CONVERTER INTERRUPT SERVICE 
;GET IDB ADDR 

;GET DEVICE CSR AND UCB ADDR 
;BRANCH IF INT UNEXPECTED, 

; AND CLEAR EXPECTED BIT 
;RESTORE REMAINING DRIVER 

; CONTEXT: R3; (R4 ALREADY SET) 
;CALL DRIVER FORK PROCESS 


RESTORE REGISTERS 


=e 8s We Be WE 


;HANDLE UNSOLICITED INTERRUPT 
;DISMISS SPURIOUS INTERRUPT 
;READ DATA BUFFER TO CLEAR ERROR 
;JOIN INTERRUPT RESTORE 


INITIALIZATION 


AD_CTLINIT - AD1L1-K CONTROLLER INITIALIZATION 


THIS ROUTINE IS CALLED AT SYSTEM STARTUP AND AFTER A POWER 


THIS WILL FORCE THE 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


IS THE RESULT OF A POWER FAILURE. THE TIMEOUT WILL OCCUR IN 0-1 
SECONDS. 
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THE DATA BUFFER REGISTER IS READ TO CLEAR A PENDING CONVERSION, 
INTERRUPT, OR ERROR FOR DEVICE INITIALIZATION. 


INPUTS: 
R4 = AD11 CSR ADDRESS 
R5 = IDB ADDRESS OF DEVICE UNIT 
R6 = ADDR OF DDB 
R8 = ADDR OF CRB 
OUTPUTS: 


ALL REGISTERS PRESERVED 
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AD_CTLINIT: 


CLRW AD CSR(R4) >CLEAR CSR (IE IN PARTICULAR) 
TSTW AD DBR(R4) >CLEAR ANY PENDING CONVERSION, 
— + INTERRUPT, OR ERROR 

RSB 7 


SAMPLE DRIVER FOR AN A-TO-D CONVERTER 


-SBTTL AD UNITINIT: AD11-K UNIT INITIALIZATION 


; AD_UNITINIT - AD11-K UNIT INITIALIZATION 


me Ne 


FAILURE. 


INPUTS: 


R5 = 


OUTPUTS: 


RO = 
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AD_UNITINIT: 
BISW 


MOVL 
MOVL 
MOVL 
RSB 


AD END: 


» END 


THIS ROUTINE IS CALLED AT SYSTEM STARTUP AND AFTER A POWER 
THE UCB AND IDB ARE INITIALIZED. 


ADDRESS OF DEVICE UCB 


IDB ADDRESS 

OTHER REGISTERS ARE PRESERVED 

UCBSW STS(R5), ONLINE BIT IS SET 

IDBSL_ OWNER (RO) = ADDRESS OF OWNING UCB 


#UCBSM ONLINE,- ;SET UNIT ONLINE 
UCBSW_STS(R5) ; 

UCBSL CRB(R5) ,RO ;GET CRB ADDRESS 
CRBSL_INTD+VECSL_ IDB(RO),RO ;GET IDB ADDR 
R5,IDBSL_OWNER(RO) ;SET UCB ADDR OF OWNING UNIT 


° 
? 


-END OF DRIVER LABEL 


APPENDIX EE 


SAMPLE DRIVER FOR DR1l1s 


This appendix contains the Source listing of a driver for two 
connected DR1ls. 


SAMPLE DRIVER FOR DR11s 


-TITLE XADRIVER - VAX/VMS DR11 DRIVER 
~IDENT ‘'V02-005' 


DIRIGO III III ICI ICICI III TOTTI CIO IIIT TI TTI AIK 
«x * 
e 
;* Copyright (c) 1979, 1980 - 
;* by DIGITAL Equipment Corporation, Maynard, Mass. > 
-* * 
g 
;* This software is furnished under a license and may be used and copied * 
7;* only in accordance with the terms of such license and with the * 
;* inclusion of the above copyright notice. This software or any other * 
;* copies thereof may not be provided or otherwise made available to any * 
;* other person. No title to and ownership of the software is hereby * 
;* transferred. * 
7% * 
;* The information in this software is subject to change without notice * 
;* and should not be construed as a commitment by DIGITAL Fquipment * 
;* Corporation. * 
3% * 
;* DIGITAL assumes no responsibility for the use or reliability of its * 
;* software on equipment which is not supplied by DIGITAL. : 
o% *& 
TORII SIIGIGIGIIOIG ISO IIOICIOGIGI IOI OCIOI ISIC IOI III IOI TI TIT Ik 
; 
ae 3 
; 
; FACILITY: 
; 
: VAX/VMS Executive, I/O Drivers 
; 
; ABSTRACT: 
: This module contains the DR11l driver: 
; 
; Tables for loading and dispatching 
; Controller initialization routine 
; FDT routine 
; The start I/O routine 
: The interrupt service routine 
: Device-specific cancel I/0 
F Error-logging register dump routine 
; ENVIRONMENT: 
: 
Kernel Mode, Nonpaged 
AUTHOR: 


S. PROGRAMMER JANUARY 1979 


MODIFIED BY: 
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SAMPLE DRIVER FOR DR1Is 


-SBTTL External and local symbol definitions 


; External symbols 


; Local 


SACBDEF 
SCRBDEF 
SDDBDEF 
SDPTDEF 
SEMBDEF 
SIDBDEF 
SIODEF 

SIPLDEF 
SIRPDEF 
SPRDEF 

SPRIDEF 
SUCBDEF 


SVECDEF 
SXADEF 


symbols 
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AST control block 
Channel request block 
Device data block 


Driver prologue table 


EMB offsets 

Interrupt data block 

I/O function codes 

Hardware IPL definitions 

I/O request packet 

Internal processor registers 
Scheduler priority increments 
Unit control block 


Interrupt vector block 
Define device specific characteristics 


; Argument list (AP) offsets for device-dependent QIO parameters 


; Other 


XA_DEF_TIMEOUT 
XA_DEF BUFSIZ 
XA_RESET_DELAY 


= 0 

= 4 

= 8 

= 12 

= 16 

= 20 

constants 
= 10 
= 65535 
= 2 
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First QIO parameter 
Second QIO parameter 
Third QIO parameter 
Fourth QOIO parameter 
Fifth QIO parameter 
Sixth QIO parameter 


10 second default device timeout 
Default buffer size 
Delay N microseconds after RESET 


* DR1l1l definitions that follow the standard UCB fields 


SDEF 
SDEF 
SDEF 
SDEF 
SDEF 
SDEF 
SDEF 
SDEF 
SDEF 
SDEF 
SDEF 


SDEF 


OT EB *** 


SDEFINI UCB 
~=UCBSL_DPC+4 
UCBSL_XA_ATTN 
~BLKL 
UCBSW_XA_CSRTMP 
~BLKW 
UCBSW_XA_BARTMP 
~BLKW 
UCBSW_XA_CSR 
~BLKW 
UCBSW XA EIR 
™~  TBLKW 
UCBSW XA IDR 
~  SBLKW 
UCBSW XA BAR 
~  YBLKW 
UCBSW XA WCR 
~ YBLKW 
UCBS$W XA ERROR 
~  YBLKW 
UCBSL XA DPR 
~ “YBLKL 
UCBSL_XA_FMPR 
~BLKL 
UCBSL_XA_PMPR 


=e 


=e 


=e 


ume 


ORDER OF THESE UCB FIELDS [IS ASSUMED 


Attention AST listhead 
Temporary Storage of CSR image 
Temporary Storage of BAR image 
Saved CSR on interrupt 

Saved EIR on interrupt 
Saved IDR on interrupt 

Saved BAR register on interrupt 
Saved WCR register on interrupt 
Saved device status flag 

Data Path Register contents 


Final Map Register contents 


Previous Map Register contents 


SAMPLE DRIVER FOR DR11s 


-BLKL 1 
SDEF | UCBSW_XA_DPRN 
-BLKW 1 


; Bit positions 
SVIELD UCB,0,<- 

<ATTNAST, ,M>,- 

<UNEXPT, ,M>,- 

> 

UCBSK_ SIZE=. 


SDEFEND UCB 


; Device register offsets from CSR address 


SDEFINI XA 
SDEF XA_WCR 
-BLKW 1 
SDEF XA_BAR 
-BLKW 1 
SDEF XA_CSR 


° 
f 
° 
’ 
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Saved Datapath Register Number 
And Datapath Parity error flag 


for device-dependent status field in UCB 


UCB device-specific bit definitions 
ATTN AST requested 
Unexpected interrupt received 


Start of DR11 definitions 
Word count 


Buffer address 


Control/status 


; Bit positions for device control/status register 


SEQULST XASK ,,0,1,<- 
<FNCT1,2>- 
<FNCT2,4>- 
<FNCT3,3>- 
<STATUSA , 2048>- 
<STATUSB ,1024>- 
<STATUSC ,512>- 

> 

SVIELD XA CSR,0,<- 

<GO,,M>,- 

<FNCT,3,M>,- 
<XBA,2,M>,- 
<IE,,M>,- 
<RDY,,M>,- 
<CYCLE, ,M>,- 
<STATUS,3,M>,- 
<MAINT, ,M>,- 
<ATTN, ,M>,- 
<NEX, ,M>,- 
<ERROR, ,M>,- 

> 
SDEF XA_EIR 


; Bit positions for error information 


SVIELD XA EIR,0,<- 
<REGFLG, ,M>,- 
<SPARE,7,M>,- 
<BURST, ,M>,- 
<DLT, ,M>,- 
<PAR, ,»M>,- 
<ACLO, ,M>,- 
<MULTI,,M>,- 
<ATTN, »M>,- 
<NEX, ,M>,- 
<ERROR, ,M>,- 
> 

-BLKW 1 


SDEF XA_IDR 


? 


’ 
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Define CSR FNCT bit values 


Define CSR STATUS bit values 


Control/status register 
Start device 

CSR FNCT bits 

Extended address bits 
Enable interrupts 

Device ready for command 
Starts slave transmit 

CSR STATUS bits 

Maintenance bit 

Status from other processor 
Nonexistent memory flag 
Error or external interrupt 


Error information register 


register 
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Error information register 

Flags whether EIR or CSR is accessed 
Unused - spare 

Burst mode transfer occurred 

Timeout for successive burst transfer 
Parity error during DATI/P 

Power fail on this processor 
Multicycle request error 

ATTN - same as in CSR 

NEX - Same as in CSR 

ERROR - same aS in CSR 


Input Data Buffer register 


SAMPLE DRIVER FOR DR1I1s 


SDEF XA_ODR > Output Data Buffer register 
-BLKW 1 


SDEFEND XA ; End of DR11 definitions 


ty 
l 
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SAMPLE DRIVER FOR DR11s 


~-SBTTL Device Driver Tables 


; Driver prologue table 


DPTAB 


END=XA_END,~ 
ADAPTER=UBA , - 
FLAGS=DPTSM_SVP,- 
UCBSIZE=UCBSK_SIZE,- 
NAME=XADRIVER 


DPT-creation macro 

End of driver label 
Adapter type 

Allocate system page table 
UCB size 

Driver name 


Start of load 
initialization table 
Device fork IPL 

Device interrupt IPL 
Device characteristics 


DPT STORE INIT 


DPT STORE UCB,UCBSB_FIPL,B,8 
DPT STORE UCB,UCBSB_DIPL,B,22 
DPT_STORE UCB,UCBSL_DEVCHAR,L,<- 
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DEVSM RTMI- Real time device 
DEVSM ELG!- Error logging enabled 
DEVSM IDV!- input device 

DEVSM ODV> output device 


DPT STORE UCB,UCBS$B DEVCLASS,B,DCS REALTIME ; Device class 

DPT STORE UCB,UCB$B DEVTYPE,B,DT$ DR11W ; Device Type 

DPT STORE UCB,UCBSW DEVBUFSIZ,W,- | Default buffer size 
XA DEF BUFSIZ 

DPT_STORE REINIT 
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Start of reload 
initialization table 
Address of DDT 
Address of interrupt 
service routine 
Address of controller 
initialization routine 
End of initialization 
tables 


DPT STORE DDB,DDBSL DDT,D,XA$DDT 

DPT STORE CRB,CRBSL INTD+4,D,- 
XA INTERRUPT 

DPT_STORE CRB,CRBSL_INTD+VECSL_INITIAL,- 
D,XA CONTROL INIT 

DPT STORE END 7 
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; Driver dispatch table 


DDT-creation macro 

Name of device 

Start I/O routine 

FDT address 

Cancel I/O routine 

REGDMP=XA REGDUMP,- Register dump routine 
DIAGBF=<<13*4>+<¢<34+5+1>*4>>,- Diagnostic buffer size 
ERLGBF=<<13*4>+<1*4>+<EMBSL_ DV_REGSAV>> ; Error log buffer size 


DDTAB- 
DEVNAM=XA, - 
START=XA_START,- 
FUNCTB=XA_FUNCTABLE,- 
CANCEL=XA_CANCEL,- 
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Function decision table 


tf 
XA FUNCTABLE: ; FDT for driver 
_ FUNCTAB ,- ; Valid I/O functions 
<READPBLK ,READLBLK ,READVBLK ,WRITEPBLK ,WRITELBLK ,WRITEVBLK ,- 
SETMODE,SETCHAR,SENSEMODE,SENSECHAR> 
FUNCTAB , > No buffered functions 
FUNCTAB XA READ WRITE,- : Device-specific FDT 
<READPBLK , READLBLK ,READVBLK ,WRITEPBLK ,WRITELBLK ,WRITEVBLK> 
FUNCTAB +EXESREAD ,<READPBLK , READLBLK , READVBLK> 
FUNCTAB +EXESWRITE, <WRITEPBLK ,WRITELBLK ,WRITEVBLK> 
FUNCTAB XA SETMODE,<SETMODE,SETCHAR> 
FUNCTAB +EXESSENSEMODE, <SENSEMODE,SENSECHAR> 


SAMPLE DRIVER FOR DR11s 


-SBTTL XA_CONTROL INIT, Controller initialization 


+ 
+ 


XA_CONTROL INIT, Called 


power failure recovery. 


Functional Description: 


R4 = address 

R5 = address 

R6 = address 

R8 = address 
Outputs: 
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XA_CONTROL_INIT: 


of CSR 
of IDB 
of DDB 
of CRB 


when driver is loaded, system is booted, or 


1) Allocates the direct data path permanently 

2) Assigns the controller data channel permanently 
3) Clears the Control and Status Register 

4) If power recovery, requests device timeout 


VECSV_PATHLOCK bit set in CRBSL_INTD+VECSB_DATAPATH 
UCB address placed into IDBSL_ OWNER 


MOVL IDB$L_UCBLST(R5) ,RO > Address of UCB 
MOVL RO, IDBSL OWNER(R5) ; Make permanent controller owner 
BISW #UCBSM ONLINE,UCBSW_STS(RO) 


; Set device status "on-line" 


; If powerfail has occurred and device was active, force device timeout. 
; The user can set his own timeout interval for each request. Timeout 
; is forced so a very long timeout period will be short-circuited. 


BBS #UCBSV_POWER,UCBSW_STS(RO) ,10$ 


; Branch if powerfail 


BISB #VECSM_PATHLOCK,CRBSL_INTD+VECSB_DATAPATH (R8) 


10S: 


BSBW  XA_DEV_RESET 


RSB 


; Permanently allocate direct datapath 


Reset DR11l 
Done 


° 
t 
r 
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SAMPLE DRIVER FOR DR11s 


-SBTTL XA_READ WRITE, FDT for device data transfers 


+ 
+} 


XA READ WRITE, FDT for READLBLK,READVBLK ,READPBLK ,WRITELBLK ,WRITEVBLK, 
WRITEPBLK 


Functional description: 


1) Rejects QUEUE I/Os with odd transfer count 

2) Rejects QUEUE I/Os for BLOCK MODE request to UBA Direct Data 
path on odd-byte boundary 

3) Stores request timeout count specified in P3 into IRP 

4) Stores FNCT bits specified in P4 into IRP 

5) Stores word to write into ODR from PS into IRP 

Checks block mode transfers for memory modify access 
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Inputs: 
R3 = Address of IRP 
R4 = Address of PCB 
R5 = Address of UCB 
R6 = Address of CCB 
R8 = Address of FDT routine 
AP = Address of Pl 
Pl] = Buffer Address 
P2 = Buffer size in bytes 
P3 = Request timeout period (conditional on IOSM_TIMED) 
P4 = Value for CSR FNCT bits (conditional on IOSM_SETFNCT) 
P5 = Value for ODR (conditional on IOSM S®TFNCT) 
P6 = Address of Diagnostic Buffer a 
; Outputs: 


RO = Error status if odd transfer count 


IRPSL_ MEDIA = Timeout count for this request 
IRPSL SEGVBN = FNCT bits for DR11 CSR and ODR image 
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XA_READ_ WRITE: 


BLBC P2(AP) ,10$ : Branch if transfer count even 
2$:3 MOVZWL #SS$_BADPARAM,RO ; Set error status code 
5$;: JMP G“EXESABORTIO ; Abort request 
10S: MOVZWL IRPSW FUNC(R3) ,R1 ; Fetch I/O function code 
MOVL P3(AP),IRPS$L_MEDIA(R3) ; Set request specific timeout count 
BBS #IOSV TIMED,R1,15$ > Branch if time-out specified 
MOVL #XA DEF TIMEOUT, IRPSL_MEDIA(R3) 
a ; Else set default timeout value 
15S: BBC #IOSV_DIAGNOSTIC,R1,20$ ; Branch if not maintenance request 
EXTZV #IOSV_FCODE,#IOSS FCODE,R1,R1 ; AND out all function modifiers 
CMPB #I0$ READPBLK,R1 ~ : If maintenance function, must be 


; physical I/O read or write 
BEQL 20$ 


CMPB #IOS$ WRITEPBLK ,R1 
BEQL 20$ 
MOVZWL #SS$_NOPRIV,RO ; No privilege for operation 
BRB 5$ ; Abort request 
20S: EXTZV #0 ,#3,P4(AP) ,RO ; Get value for FNCT bits 
ASHL #XA CSRSV FNCT,RO,IRPSL SEGVBN(R3) ; Shift into position for CSR 


MOVW P5 (AP) ,IRPSL_ SEGVBN+2(R3) ; Store ODR value for later 


SAMPLE DRIVER FOR DR1I1s 


If this is a block mode transfer, check buffer for modify access 
whether or not the function is read or write. The DR11 does 
not decide whether to read or write, the user's device does. 
For word mode requests, return to read check or write check. 


If this is a BLOCK MODE request and the UBA Direct Data Path is 
in use, check the data buffer address for word alignment. If buffer 
is not word aligned, reject the request. 
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BBS #IOSV_WORD, IRPSW_FUNC (R3) ,308 
:; Branch if word mode transfer 


BBS #XASV_DATAPATH,UCBSL_DEVDEPEND(RS5) ,25$ 

; Branch if Buffered Data Path in use 
DDP, branch on bad alignment 
Check buffer for modify access 
Return 


BLBS P1(AP) ,2S$ 
258: JMP G“EXESMODIFY 
30S: RSB 
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~SBTTL 


3 ++ 
~ XA_SETMODE, FD 


Functional des 


If IOSM 


Inputs: 
R3 = I/0 
R4 = PCB 
R5 = UCB 
R6 = CCB 
R7 = Fun 
AP = QIO 

Outputs: 


Else, us 
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XA_SETMODE: 
MOV ZWL 


BBC 
; Attention AST 


PUSHR 
MOVAB 
JSB 
POPR 
BLBC 
BISW 


BBC 


BSBW 
10$: JMP 


SAMPLE DRIVER FOR DR1I1s 


XA_SETMODE, Set Mode, Set characteristics FDT 


T routine to process SET MODE and SET CHARACTERISTICS 
cription: 


ATTNAST modifier is set, queue attention AST for device 


If IOSM DATAPATH modifier is set, queue packet. 
Else, finish I/O. 


packet address 

address 

address 

address 
ction code 

Paramater list address 


If IOSM _ATTNAST is specified, queue AST on UCB attention AST list. 
If IOSM_DATAPATH is specified, queue packet to driver. 


e exec routine to update device characteristics 


IRPSW_FUNC(R3) ,RO ; Get entire function code 
#IOSV_ATTNAST,RO,20S ; Branch if not an ATTN AST 

request 

#°M<R4,R7> 

UCBSL_ XA_ATTN(R5) ,R7 ; Address of ATTN AST control block list 
G*COMSSETATTNAST ; Set up attention AST 

#°M<R4,R7> 

RO,50$ : Branch if error 


#UCBSM ATTNAST,UCBSW DEVSTS(R5) 
i Zz : Flag ATTN AST expected. 
#UCBSV UNEXPT,UCBSW DEVSTS(R5) ,10$ 
~ = ; Deliver AST if unsolicited interrupt 
DEL_ATTNAST 
G“EXESFINISHIO : That's all for now 


E-10 


SAMPLE DRIVER FOR DR1I1s 


If modifier IOSM DATAPATH is set, 
queue packet. The data path is changed at driver level to preserve 
order with other requests. 
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20S; BBS S°#IOSV_DATAPATH,RO,30$ ; If BDP modifier set, queue packet 
JMP G“EXESSETCHAR > Set device characteristics 
; This is a request to change data path usage, queue packet 


Set characteristics? 


308: CMPL #IOS SETCHAR,R7 ; 
BNEQ 45S ; No, must have the privilege 
JMP G° EXESSETMODE > Queue packet to start I/0 


; Error, abort I0 


45S: MOVZWL #SSS_NOPRIV,RO ; No priv for operation 
509% CLRL Rl 
JMP G”EXESABORTIO ; Abort I/O on error 


SAMPLE DRIVER FOR DR1Is 


-SBTTL XA START, Start I/0 routines 


+ 
+ 


XA START ~ Start a data transfer, set characteristics, enable ATTN AST. 
Functional Description: 
This routine has two major functions: 


1) Start an I/O transfer. This transfer can be in either word 
or block mode. The FNCTN bits in the DR11 CSR are set. If 
the transfer count is zero, the STATUS bits in the DR11 CSR 
are read and the request completed. 

2) Set Characteristics. If the function is change data path, the 
new data path flag is set in the UCB. 


Inputs: 
R3 = Address of the I/O request packet 
R5 = Address of the UCB 

Outputs: 


RO = final status and number of bytes transferred 

Rl = value of CSR STATUS bits and value of input data buffer register 
Device errors are logged 

Diagnostic buffer is filled 
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e-ENABL LSB 
XA_START: 
; Retrieve the address of the device CSR 


ASSUME IDBSL CSR EQ 0O 
MOVL UCBSL_CRB(R5) ,R4 ; Address of CRB 
MOVL @CRBSL INTD+VECSL IDB(R4) ,R4 

= = ; Address of CSR 


; Fetch the I/O function code 


MOVZWL IRPSW_FUNC(R3) ,R1 : Get entire function code 
MOVW R1,UCBSW FUNC(RS5) ; Save FUNC in UCB for error logging 
EXTZV #IOSV_FCODE,#IOSS FCODE,R1,R2 ; Extract function field 


Dispatch on function code. If this is SET CHARACTERISTICS, we will 
select a data path for future use. 

If this is a transfer function, it will either be processed in word 
or block mode. 
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CMPB #IOS SETCHAR,R2 > Set characteristics? 
BNEQ 3$ 


+ 
+ 


SET CHARACTERISTICS - Process Set Characteristics QIO function 
INPUTS: 
XA_DATAPATH bit in Device Characteristics specifies which data path 


to use. If bit is a one, use buffered data path. If zero, use 
direct datapath. 
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SAMPLE DRIVER FOR DRI11s 


OUTPUTS: 


CRB is flagged as to which datapath to use. 

DEVDEPEND bits in device characteristics are updated 
XA DATAPATH = 1 -> buffered data path in use 

XA_DATAPATH = 0 -> direct data path in use 
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MOVL UCBSL CRB(R5) ,RO ; Get CRB address 

MOVQ IRPSL MEDIA(R3) ,UCBSB DEVCLASS(R5) ; Set device characteristics 

BISB #VECSM PATHLOCK,CRBSL INTD+VECSB DATAPATH (RO) 

- 7 : Assume direct datapath 

BBC #XASV_DATAPATH, UCBSL_DEVDEPEND(R5) ,2$ > Were we right? 
s BICB #VECSM PATHLOCK,CRBSL INTD+VECSB DATAPATH(RO) ; Set buffered datapath 
28: = = a 

CLRL Rl ; Return Success 

MOVZWL #SS$_ NORMAL ,RO 

REQCOM 


; If subfunction modifier for device reset is set, do one here 


3S: BBC S“#IOSV_RESET,R1,4$ ’ : Branch if not device reset 
BSBW XA_DEV_RESET ; Reset DR1l 


This must be a data transfer function - i.e. READ OR WRITE 
Check to see if this is a zero length transfer. 
If so, only set CSR FNCT bits and return STATUS from CSR 
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4S: TSTW UCBSW BCNT(RS5) > Is transfer count zero? 
BNEQ 10s ; No, continue with data transfer 
BBC S“#IOSV SETFNCT,R1,5$ ; Set CSR FNCT specified? 
DSBINT a 
MOVW IRPSL_SEGVBN+2(R3) ,XA_ODR(R4) 


; Store word in ODR 
MOVZWL XA_CSR(R4) ,RO 


BICW #<XA_CSRSM_FNCT!XA_CSRSM_ERROR>,RO 
BISW IRPSL_SEGVBN(R3) ,RO = 
MOVW RO,XA_CSR(R4) 
BBC #XASV_LINK,UCBSL_DEVDEPEND(R5) ,5S : Link mode? 
BICW3 #XASK_FNCT2,R0,XA_CSR(R4) ; Make FNCT bit 2 a pulse 
5S: 
ENBINT 
6S: 
BSBW XA REGISTER ; Fetch DR11 registers 
BLBS RO,78 : If error, then log it 
JSB G“ERLSDEVICERR ; Log a device error 
79% JSB G* IOCSDIAGBUFILL ; Fill diagnostic buffer if specified 
MOVL UCBSW XA CSR(R5),R1l ; Return CSR and EIR in Rl 
MOVZWL UCBSW XA ERROR(R5),RO ; Return status in RO 
BISB #XA CSRSM IE,XA CSR(R4) ; Enable device interrupts 
REQCOM ~ - = ; Request done 


; Build CSR image in RO for later use in starting transfers 


10$ 


DIVW3 #2,UCBSW_BCNT(R5) ,UCBSL_XA_DPR(R5) 
fe ; Make byte count into word count 
MOVZWL XA CSR(R4) ,RO 


BICW #°C<XA_CSRSM_FNCT> ,RO 
BISW #XA_CSRSM_IE,RO Set Interrupt Enable 
BBC S“#IO$V_SETFNCT,R1,20$ Set FNCT bits in CSR? 


BICW #<XA CSRSM FNCT>,RO 


3 i Yes, Clear previous FNCT bits 
BISB IRPSL_SEGVBN (R3) ,RO 


OR in new value 
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SAMPLE DRIVER FOR DR11s 


20S: BBC S"#IO$V_DIAGNOSTIC,R1,235S ; Check for maintenance function 
BISW #XA_CSRSM_MAINT,RO ; Set maintenance bit in CSR image 


; Is this a word mode or block mode request? 


238: MOVW RO,UCBSW_XA_CSRTMP(R5) ; Save CSR image in UCB 
BBC S“#IOSV_WORD,R1,BLOCK MODE ; Check if word or block mode 
BRW WORD MODE ; Branch to handle word mode 


SAMPLE DRIVER FOR DR11s 


fa aie 
BLOCK MODE -- Process a Block Mode (DMA) transfer request 


FUNCTIONAL DESCRIPTION: 


; 

; 

? 

7 

; This routine takes the buffer address, buffer size, function code, 

: and function modifier fields from the IRP. It calculates the UNIBUS 
i 

; 

7 

i 


address, allocates the UBA map registers, loads the DR1l1l device 
registers and starts the request. 


Set up UBA 
Start transfer 


BLOCK MODE: 
; If IOSM CYCLE subfunction is specified, set CYCLE bit in CSR image 


BBC #IOSV_CYCLE,R1,258 * Set CYCLE bit in CSR? 
BISW #XA_CSRSM_CYCLE,UCBSW_XA_CSRTMP(R5) ; If yes, or into CSR image 


; Allocate UBA data path and map registers 


255% 
REQDPR ; Request UBA data path 
REQMPR ; Request UBA map registers 
LOADUBA ; Load UBA map reqisters 


Calculate the UNIBUS transfer address for the DR11 from the UBA 
map register address and byte offset. 
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MOVZWL UCBSW_BOFF(R5),R1 ; Byte offset in first page of transfer 
MOVL UCBSL CRB(R5) ,R2 ; Address of CRB 
INSV CRBSL_INTD+VECSW_MAPREG(R2) ,#9,#9,R1 
; Insert page number 
Extract bits 17:16 of bus address 
ASHL #XA_CSRSV_XBA,R2,R2 Shift extended memeroy bits for CSR 
BISW #XA CSRSM GO,R2 Set "GO" bit into CSR image 
BISW R2,UCBSW_XA_CSRTMP(R5) ; Set into CSR image we are building 
BICW3  #<XA_CSRSM _GO!XA_CSRSM_CYCLE>,UCBSW_XA_CSRTMP(R5) ,RO 

; CSR image less "GO" and "CYCLE" 
BICW3 #XASK_FNCT2,UCBSW_XA_CSRTMP(R5) ,R2 ; CSR image less FNCT bit 2 
MOVW R1,UCBSW_XA_BARTMP(R5) ; Save BAR for error-logging 


EXTZV #16,#2,R1,R2 
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At this juncture: 


RO = CSR image less "GO" and "CYCLE" 
Rl = low 16 bits of transfer bus address' 
R2 = CSR image less FNCT bit 2 


UCBSL_XA_DPR(R5) = transfer count in words 
UCBSW_XA_CSRTMP(R5) = CSR image to start transfer with 
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Set DR11l registers and start transfer 

Note that read-modify-write cycles are NOT performed to the DR11 CSR. 

The CSR is always written directly into. This prevents inadvertently setting 
the EIR select flag (writing bit 15) if error happens to become true. 
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DSBINT ; Disable interrupts (powerfail) 
MNEGW  UCBSL_XA DPR(R5) ,XA_WCR(R4) 
; Load negative of transfer count 


MOVW R1,XA BAR(R4) >: Load low 16 bits of bus address 
MOVW RO ,XA_CSR(R4) ; Load CSR image less "GO" and "CYCLE" 
BBC #XASV_LINK,UCBSL_ DEVDEPEND(RS) ,26$ ; Link mode? 


MOVW R2,XA_CSR(R4) ; Yes, load CSR image less "FNCT" bit 2 


; Only if link mode in dev characteristics 


=> 


7] 


26S: 


; Wait for transfer complete interrupt, 


; Device has interrupted, 


; Handle request completion, 


27S: 


28S: 


; Check 


30S: 


358: 


40S: 


WFIKPCH XA_TIME OUT,IRPSL MEDIA(R3) 7 


IOFORK 


MOV ZWL 
CLRW 
PURDPR 
BLBS 
MOV ZWL 
INCB 
MOVL 
EXTZV 


MOVB 
EXTZV 
EXTZV 
INSV 
CMPW 
BGTR 
MOVL 
CLRL 
DECL 
CMPV 


BGTR 
MOVL 
RELMPR 
RELDPR 


SAMPLE DRIVER FOR DR11s 


powerfail, or device timeout 
Wait for interrupt 
FORK 

; FORK to lower IPL 
release UBA resources, check for errors 


#SS$_NORMAL,- (SP) 
UCBSW_XA_DPRN(RS5) 


Assume success, store code on stack 
Clear DPR number and DPR error flag 
Purge UBA buffered data path 

Branch if no datapath error 

Flag parity error on device 

Flag PDR error for log 

Save data path register in UCB 
#VECSV_DATAPATH,- Get datapath register no. 

#VECSS DATAPATH,- For error log 

CRBSL INTD+VECSB _DATAPATH(R3) , RO 

RO,UCBSW XA DPRN(RS) :; Save for later in UCB 
#9,#7,UCBSW_XA_BAR(RS),RO ; Low bits, final map register no. 
#4,#2, UCBSW_ XA _CSR(R5),R1 ; High bits of map register no. 


RO,27$ 
#SSS_PARITY, (SP) 
UCBSW XA DPRN#+¥1(R5) 
R1,UCBSL XA DPR(RS) 
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Rl,#7,#2,RO ; Entire map register number 

RO, £496 ; Is map register number in range? 
28$ ; No, forget it - compound error 
(R2) [RO] ,UCBSL XA _FMPR(R5) ; Save map register contents 
UCBSL_XA _PMPR(RS) ~ ; Assume no previous map register 

RO ; Was there a previous map register? 


#VECSV_MAPREG,#VECSS_MAPREG ,- 

CRBSL _ INTD+VECSW _MAPREG(R3), RO 

28S : No if greater 

(R2) [RO] ,UCBSL_XA_FMPR(R5) ; Save previous map register contents 
: Release UBA resources 


for errors and return status 


TSTW 
BEQL 
MOV ZWL 
BBC 
MOV ZWL 
BSBW 
BLBS 
JSB 
BSBW 
JSB 
MOVL 
MULW3 
ADDW 
INSV 
MOVL 
BISB 
REQCOM 


-DSABL 


UCBSW_XA_WCR(R5) All words transferred? 
30$ Yes 

#SSS OPINCOMPL, (SP) No, flag operation not 
#XA_CSRSV_ ERROR, UCBSW XA CSR(R5),35S ; Branch on 


UCBSW XA ERROR (R5) , (SP) Flag for controller/drive error status 
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complete 
CSR error bit 


XA_DEV_RESET >; Reset DR11 

(SP) ,40S :; Any errors after all this? 

G*“ ERLSDEVICERR ; Yes, log them 

DEL ATTNAST ; Deliver outstanding ATTN ASTs 
G* LOCSDIAGBUFILL ; Fill diagnostic buffer 
(SP)+,R0 ; Get final device status 
#2,UCBSW XA WCR(R5),R1l ; Calculate final transfer count 


UCBSW_BCNT(R5) ,R1 
R1,#16,#16,R0 
UCBSW_XA_CSR(R5) ,R1 
#XA_CSRSM_IE,XA_CSR(R4) 


Insert into high byte of IOSB 
Return CSR and EIR in IOSB 
Enable interrupts 

Finish request in exec 
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LSB 


SAMPLE DRIVER FOR DR1I1s 


+ 
+ 


WORD MODE -- Process word mode (interrupt per word) transfer 
FUNCTIONAL DESCRIPTION: 


Data is transferred one word at a time with an interrupt for each word. 
The request is handled separately for a write (from memory to DR11 

and a read (from DR11 to memory). 

For a write, data is fetched from memory, loaded into the ODR of the 
DRl1 and the system waits for an interrupt. For a read, the system 
waits for a DR11 interrupt and the IDR is transferred into memory. 

If the unsolicited interrupt flag is set, the first word is transferred 
directly into memory withou waiting for an interrupt. 
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-ENABL LSB 
WORD MODE: 


; Dispatch to separate loops on READ or WRITE 


CMPB #10$ READPBLK ,R2 ; Check for read function 
BEQL 30$ 

++ 

WORD MODE WRITE -- Write (output) in word mode 


FUNCTIONAL DESCRIPTION: 


Transfer the requested number of words from user memory to 
the DR11l ODR one word at a time, wait for interrupt for each 
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word. 
LOS: 

BSBW MOVFRUSER ; Get two bytes from user buffer 

DSBINT ; Lock out interrupts 

; Flag interrupt expected 

MOVW R1,XA ODR(R4) ; Move data to DR1l 

MOVW UCBSW XA CSRTMP(R5) ,XA CSR(R4) ; Set DR11 CSR 

BBC #XASV_LINK,UCBSL_ DEVDEPEND(R5),15$ ; Link mode? 

BICW3 #XASK_FNCT2,UCBSW XA_CSRTMP(R5) ,XA_CSR(R4) ; Clear interrupt FNCT bit 2 

a ; Only if link mode specified 

15S: 


; Wait for interrupt, powerfail, or device timeout 
WFIKPCH XA_TIME_OUTW,IRPSL_ MEDIA(R3) 
; Check for errors, decrement transfer count, and loop until complete 


IOFORK ; Fork to lower IPL 
BITW #XA_EIRSM_NEX!- 
XA EIRSM MULTI! - 
XA_EIRSM_ACLO!- 
XA EIRSM PAR!- 
XA_EIRSM_DLT,UCBSW_XA_EIR(R5) ; Any errors? 


BEQL 20S ; No, continue 
BRW 40$ > Yes, abort transfer. 

20S: DECW UCBSL XA DPR(R5) ; All words transferred? 
BNEQ 10$ ; No, loop until finished. 


; Transfer is done, clear interrupt expected flag and FORK 
; All words read or written in WORD MODE. Finish I/O. 


SAMPLE DRIVER FOR DR1is 


RETURN STATUS: 


JSB G* IOCSDIAGBUFILL 
BSBW DEL_ATTNAST 
MOVZWL #SSS_NORMAL ,RO 

228: MULW3 #2, UCBSL_XA_DPR(R5) ,R1 
SUBW3 R1,UCBSW _BCNT(RS5) ,Rl 
INSV R1,#16,#16 ,RO 
MOVL UCBSW_XA_CSR(RS) ,R1 
BISB #XA_CSRSM_IE,XA_CSR(R4) 
REQCOM 7 


Fill diagnostic buffer if present 
Deliver outstanding ATTN ASTs 
Complete success status 

Calculate actual bytes transferred 
From requested number of bytes 

And place in high word of RO 
Return CSR and EIR status 

Enable device interrupts 

Finish request in executive 


C) 
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+ 
+ 


WORD MODE READ -- Read (input) in word mode 
FUNCTIONAL DESCRIPTION: 


Transfer the requested number of words from the DR11 IDR into 

user memory one word at a time, wait for interrupt for each word. 
If the unexpected (unsolicited) interrupt bit is set, transfer the 
first (last received) word to memory without waiting for an 
interrupt. 
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30S: 
SETIPL UCBSB_DIPL(RS5) ; Lock out interrupts 


; If an unexpected (unsolicited) interrupt has occurred, assume it 
; is for this READ request and return value to user buffer without 


; waiting for an interrupt. 


BBSC #UCBSV_UNEXPT,UCBSW_DEVSTS(R5) ,37S$ 
; Branch if unexpected interrupt 
DSBINT 
358: 


; Wait for interrupt, powerfail, or device timeout 
WFIKPCH XA_TIME OUTW,IRPSL_MEDIA(R3) 
; Check for errors, decrement transfer count and loop until done 


ITOFORK : Fork to lower IPL 
37S: 
BITW #XA EIRSM NEX!- 
XA_EIRSM_MULTI!- 
XA_EIRSM_ACLO!- 
XA EIRSM PAR! - 
XA_EIRSM_DLT,UCBSW_XA_EIR(R5) ; Any errors? 
BNEQ 40S : Yes, abort transfer. 
BSBW MOVTOUSER ; Store two bytes into user buffer 


; Send interrupt back to sender. Acknowledge we got last word. 


DSBINT 

MOVW UCBSW_XA_CSRTMP(R5) ,XA_CSR(R4) 

BBC #XASV_LINK,UCBSL_DEVDEPEND(R5) ,38$ ; Link mode? 

BICW3 #XASK_FNCT2,UCBSW_XA_CSRTMP(R5) ,XA_CSR(R4) ; Yes, clear FNCT 2 
38S: 

DECW UCBSL_XA_DPR(R5) ; Decrement transfer count 

BNEQ 35$ ; Loop until all words transferred 

ENBINT 

BRB RETURN STATUS ; Finish request in common code 


SAMPLE DRIVER FOR 


: Error detected in word mode transfer 


40S: 
| BSBW DEL_ATTNAST 
BSBW XA_DEV_RESET ; 
JSB G* IOCSDIAGBUFILL ; 
JSB G”°ERLSDEVICERR ; 
MOVZWL UCBSW_XA_ERROR(R5),RO~ ; 
BRW 228 


-DSABL LSB 


INPUTS: 


R5 = UCB address 
OUTPUTS: 


Rl = Two bytes of data from users 
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=e 


~-ENABL LSB 


MOVFRUSER: 
MOVAL -(SP) ,R1l : 
MOVZBL #2,R2 : 
JSB G~ IOCSMOVFRUSER . 
MOVL (SP)+,R1 ‘ 
BRB 20S : 


INPUTS: 


R5 = UCB address 
UCBSW_XA_IDR(R5) = Location where 


OUTPUTS: 


UCB iS updated. 


OVTOUSER: 
MOVAB UCBSW XA IDR(R5),R1 ; 
MOVZBL #2,R2  ~ 
JSB G* IOCSMOVTOUSER : 
20S: : ; 
ADDW #2,UCBSW_BOFF(R5) : 
BICW #°C<"XO1FF>,UCBSW BOFF(R5 
BNEQ 30S =~ : 
ADDL #4,UCBSL SVAPTE(R5) ; 
30S = 
RSB 


-DSABL LSB 
- PAGE 


DRl1s 


Deliver ATTN AST's 

Error, reset DR1l1 

Fill diagnostic buffer if present 
Log device error 

Set controller/drive status in RO 


MOVFRUSER - Routine to fetch two bytes from user buffer. 


buffer 


Buffer descriptor in UCB is updated. 


Address of temporary stack loc 
Fetch two bytes 

Call exec routine to do the deed 
Retreive the bytes 

Update UCB buffer pointers 


MOVTOUSER - Routine to store two bytes into users buffer. 


two bytes are saved 


Two bytes are stored in user buffer and buffer descriptor in 


Address of internal buffer 


Call exec 


Update buffer pointers in UCB 
Add two to buffer descriptor 


: Modulo the page size 
If NEQ, no page boundary crossed 
Point to next page 


SAMPLE DRIVER FOR DRIIs 


~-SBTTL DR1l DEVICE TIMEOUT 


+ 
+ 


DR11 device TIMEOUT 

If a DMA transfer was in progress, release UBA resources. 

For DMA or WORD mode, deliver ATTN ASTs, log a device timeout error, 
and do a hard reset on the controller. 


Clear DR1l1 CSR 
Return error status 


Power failure will appear as a device timeout 


St ee ee | ee, i ee, ee | ee, | ee, Ye. | | 


~ENABL LSB 


XA_TIME OUT: Timeout for DMA transfer 


us 


SETIPL UCBSB FIPL(R5) Lower to FORK IPL 


; 
PURDPR ; Purge buffered data path in UBA 
RELMPR ; Release UBA map registers 
RELDPR ; Release UBA data path 


XA_TIME_ OUTW: Timeout for WORD mode transfer 


=e 


And deliver the ASTs 
Reset controller 
Error status 


BSBW DEL ATTNAST 
BSBW XA_DEV_RESET 
MOVZWL #SSS_TIMEOUT,RO 


MOVL UCBSL_CRB(R5) ,R4 ; Fetch address of CSR 
MOVL @CRBSL_ INTD+VECSL_ IDB (R4) ,R4 

BSBW XA REGISTER ; Read DR11l registers 
JSB G* TOCSDIAGBUFILL ; Fill diagnostic buffer 
JSB G* ERLSDEVICTMO ; Log device timeout 


CLRL Rl 

CLRW UCBSW DEVSTS(R5) Clear ATTN AST flags 

BICW #<UCBSM TIM! UCBSM __ INTLUCBSN TIMOUT!UCBSM | CANCEL! UCBSM _ POWER>D ,- 
UCBSW_STS(R5) ; Clear unit status flags 

REQCOM ; Complete I/O in exec 

-DSABL LSB 

- PAGE 
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SAMPLE DRIVER FOR DRI1I1s 


~SBTTL XA_INTERRUPT, Interrupt service routine for DR1ll 


+ 
+ 


XA_INTERRUPT, Handles interrupts generated by DR11 
Functional description: 


This routine is entered whenever an interrupt is generated 

by the DR11. It checks that an interrupt was expected. 

If not, it sets the unexpected (unsolicited) interrupt flag. 

All device registers are read and stored into the UCB. 

If an interrupt was expected, it calls the driver back at its Wait 
For Interrupt point. 

Deliver ATTN ASTs if unexpected interrupt. 


ue %~e *eo *O0 "6 We Be WS We We We WS 


; Inputs: 
: OO(SP) = Pointer to address of the device IDB 
: 04(SP) = saved RO 

O8(SP) = saved Rl 

12(SP) = saved R2 

16(SP) = saved R3 

20(SP) = saved R4 

24(SP) = saved R5 

28(SP) = saved PSL 

32(SP) = saved PC 


td 

a 

; 

; 

; 

7 

; Outputs: 
i 

; The driver is called at its Wait For Interrupt point if an 
; interrupt was expected. 

: The current value of the DR11 CSRs are stored in the UCB. 

; 
Se 

XA_ INTERRUPT: 


MOVL @(SP)+,R4 
MOVO (R4) ,R4 


Interrupt service for DR1l 
Address of IDB and pop SP 
CSR and UCB address from IDB 


me 66 6M 


; Read the DR11 device registers (WCR, BAR, CSR, EIR, IDR) and store 
; Into UCB. 


BSBW XA_REGISTER ; Read device registers 
; Check to see if device transfer request active or not 


If so, call driver back at Wait for Interrupt point and 
; Clear unexpected interrupt flag. 


=e 


20S: BBCC #UCBSV_INT,UCBSW_STS(R5) ,25$ 
; If clear, no interrupt expected 


; Interrupt expected, clear unexpected interrupt flag and call driver 
; back 
td e 


BICW #UCBSM_UNEXPT,UCBSW_DEVSTS(R5) 
; Clear unexpected interrupt flag 
MOVL UCBSL FR3(R5) ,R3 > Restore drivers R3 
JSB @UCBSL FPC(R5) > Call driver back 
BRB 30S 


SAMPLE DRIVER FOR DRlis 


; Deliver ATTN ASTs if no interrupt expected and set unexpected 
3 interrupt flag. 


25S: 
BISW #UCBSM_UNEXPT,UCBSW_DEVSTS(R5) ; Set unexpected interrupt flag 
BSBW DEL_ATTNAST ; Deliver ATTN ASTs 
BISB #XA_CSRSM_IE,XA_CSR(R4) ; Enable device interrupts 


; Restore registers and return from interrupt 


30S: 
POPR #°M<RO,R1,R2,R3,R4,R5> ; Restore registers 
REI :; Return from interrupt 
- PAGE 


+ 
+ 
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SAMPLE DRIVER FOR DR11s 


~SBTTL XA_REGISTER - Handle DR11 CSR transfers 
XA_REGISTER - Routine to handle DR1l register transfers 
INPUTS: 


R4 - DR11l CSR address 
R5 - UCB address of unit 


OUTPUTS: 


CSR, EIR, WCR, BAR, IDR, and statuS are read and stored into UCB. 
The DR11 is placed in its initial state with interrupts enabled. 
RO - .true. if no hard error 

false. if hard error (cannot clear ATTN) 


If the CSR ERROR bit is set and the associated condition can he cleared, then 
the error is transient and recoverable. The status returned is SSS_DRVERR. 
If the CSR ERROR bit is set and cannot be cleared by clearing the CSR, then 
this is a hard error and cannot be recovered. The returned status is 
SS$_CTRLERR. 


RO,R1 - destroyed, all other registers preserved. 


XA_REGISTER: 


MOVZWL #SS$ NORMAL ,RO 

MOVZWL XA _CSR(R4) ,R1 

MOVW R1,UCBSW_XA_CSR(R5) 
BBC #XA CSRSV ERROR,R1,55S 
MOVZWL #SSS DRVERR,RO 


Assume success 

Read CSR 

Save CSR in UCB 
Branch if no error 
Assume "drive" error 
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558: BICW #°C<XA CSRSM FNCT>,R1 Clear all uninteresting bits for later 
BISB #<XA_CSRSM_ERROR/256>,XA_ CSR+1(R4) ; Set EIR flag 
MOVW XA_EIR(R4),UCBSW_XA_EIR(R5) ; Save EIR in UCB 
MOVW R1,XA CSR(R4) ; Clear EIR flag and errors 
MOVW XA_CSR(R4) ,R1 ; Read CSR back 
BBC #XA CSRSV ATTN,R1,60$ ; If attention still set, hard error 
MOVZWL #SSS5_CTRLERR,RO ; Flag hard controller error 

60S: MOVW XA IDR(R4),UCBSW XA IDR(R5) ; Save IDR in UCB 


MOVW XA_BAR(R4) ,UCBSW_XA_BAR(R5) 

MOVW XA_WCR(R4) ,UCBSW_XA_WCR(R5) 

MOVW RO,UCBSW_XA_ERROR(R5) ; Save status in UCB 
RSB 


SAMPLE DRIVER FOR DRI11S 


-SBTTL XA CANCEL, Cancel I/O routine 


itt 
XA_CANCEL, Cancels 


if transfer i 
request. 


sc “Se “8 Se “@ “We BS Be Te We 


an I/O operation in progress 


Functional description: 


Flushes attention AST queue for the user. 


n progress, do a device reset to DR11 and finish the 


clear interrupt expected flag. 


Inputs: 
: R2 = negated value of channel index 
; R3 = address of current IRP 
: R4 = address of the PCB requesting the cancel 
; R5 = address of the device's UCB 
; Outputs: 
XA_ CANCEL: ; Cancel I/0 
BBCC #UCBSV_ATTNAST,UCBSW_DEVSTS(R5) ,20S 


:; ATTN AST enabled? 


; Finish all ATTN ASTs for this process. 


PUSHR  #*M<R2,R6,R7> 


MOVL R2,R6 


MOVAB UCBSL_XA_ATTN(R5) ,R7 
JSB G* COMSFLUSHATTNS 


Set up channel number 
Address of listhead 
Flush ATTN ASTs for process 


=e “6 “Oe 


POPR #“M<R2,R5,R7> 


; Check to see if ad 


ata transfer request is in progress 


; for this process on this channel 


20S: 
SETIPL UCBSB DIPL(RS5) ; Lock out device interrupts 
JSB G* IOCSCANCELIO > Check if transfer going 
BBC #UCBSV_CANCEL,UCBSW_STS(R5) ,30$ »* Branch if not for this guy 


Tf BLOCK mode DMA r 
; If transfer is in p 


equest in progress, release UBA resources 
rogress, do a device reset to DRII 


BBC #UCBSV INT,UCBSW STS(R5) ,25$ ; Branch if transfer not in progress 
BBS #IOSV_WORD,IRPS$W FUNC(R3) ,25$ ; Branch if not BLOCK mode transfer 
PUSHR #°M<R2,R3,R4> ; Save some registers 

MOVL UCBSL CRB(R5) ,R4 ; Get CRB address 

MOVL @CRBSL_INTD+8(R4) ,R4 ; Get pointer to CSR in IDB 

BSBW XA DEV RESET ; Reset DR1l1 

PURDPR = > ; Purge UBA buffered data path 
RELMPR ; Release UBA map registers 

RELDPR ; Release UBA data path register 
POPR #“M<R2,R3,R4> 


E-24 


25$ 


30$ 


MOV ZWL 
CLRL 


CLRW 
BICW 


REQCOM 
SETIPL 


RSB 
- PAGE 


SAMPLE DRIVER FOR DR1I1s 


#SSS CANCEL,RO ; Status is request canceled 
Rl 

UCBSW DEVSTS(R5) ; Clear unexpected interrupt flag 
#<UCBSM TIM!UCBSM BSY!UCBSM_CANCEL!IUCBSM INT!UCBS$M TIMOUT> ,- 
UCBSW_STS(R5) ; Clear unit status flags 


; Jump to exec to finish I/0 


Lower to FORK IPL 


UCBSB_FIPL(R5) ; 
; Return 


E=25 


;+t+ 
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~-SBTTL 


SAMPLE DRIVER FOR DR1lls 


DEL_ATTNAST, Deliver ATTN ASTs 


DEL _ATTNAST, Deliver all outstanding ATTN ASTs 


Functional description: 


This routine is used by the DR11l driver to deliver all of the 
outstanding attention ASTs. It is copied from COMSDELATTNAST in 
the exec. In addition, it places the saved value of the PR11 CSR 
and Input Data Buffer Register in the AST paramater. 


Inputs: 
R5 = UCB 
Outputs: 


RO,R1,R2 
R3,R4,R5 


EL_ATTNAST: 


BBCC 


PUSHR 
MOVL 
MOVAB 
MOVL 
BEQL 
BICW 
MOVL 
MOVW 


MOVW 


PUSHAB 
FORK 


of DR11 unit 


Destroyed 
Preserved 


#UCBSV_ATTNAST,UCBSW DEVSTS(R5) ,30$ 
; Any ATTN ASTS expected? 


#“M<R3,R4,R5> Save R3,R4,R5 


f 
8(SP),R1 ; Get address of UCB 
UCBSL XA ATTN(R1) ,R2 ; Address of ATTN AST listhead 
(R2),R5 > Address of next entry on list 
20S > No next entry, end of loop 
#UCBSM UNEXPT,UCBSW DEVSTS(R1) ; Clear unexpected interrupt flag 
(R5),(R2) ; Close list 


UCBSW_XA IDR(R1) ,ACBSL_ KAST+6 (R5) 
7 ; Store IDR in AST paramater 
UCBSW XA CSR(R1),ACBSL KAST+4(R5) 
_ ~ 3 Store CSR in AST paramater 
B710$ ; Set return address for FORK 
; FORK for this AST 


; AST fork procedure 


20S: 
30S: 


MOVO 


MOVB 
MOVL 
CLRL 
MOV ZBL 
JMP 


POPR 
RSB 
- PAGE 


ACBSL KAST(R5) ,ACBSL AST(RS5) 
“ = + Rearrange entries 
ACBSL_KAST+8 (R5) ,ACB$B_RMOD(R5) 
ACBSL KAST+12(R5) ,ACBSL PID(RS) 
ACBSL KAST(RS) = 


#PRIS IOCOM,R2 ; Set up priority increment 
G”“SCHSQAST > Queue the AST 
# M<R3,R4,R5> ; Restore registers 

; Return 


ie oe 
XA_REGDUMP - DR11 Register dump routine. 
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buffer. 


~SBTTL 


Inputs: 


SAMPLE DRIVER FOR DR11s 


XA_REGDUMP - DR11 register dump routine 


This routine is called to save the controller registers in a specified 
It is called from the device error-logging routine and from the 
diagnostic buffer fill routine. 


RO - Address of register save buffer 
R4 - Address of Control and Status Register 
R5 - Address of UCB 


,Outputs: 


The controller registers are saved in the specified buffer. 


CSRTMP —- The last command written to the DR11 CSR by 
by the driver. 

BARTMP —- The last value written into the DR1l1 BAR by 
the driver during a block mode transfer. 

CSR - The CSR image at the last interrupt 

EIR - The EIR image at the last interrupt 

IDR - The IDR image at the last interrupt 

BAR - The BAR image at the last interrupt 

WCR - Word count register 

ERROR - The system status at request completion 

PDRN - UBA Datapath Register number 

DPR - The contents of the UBA Data Path register 

FMPR - The contents of the last UBA Map register 

PMRP - The contents of the previous UBA Map register 

DPRF - pace for purge datapath error 

no purge datapath error 

parity error when datapath was purged 


1 


Note that the values stored are from the last completed transfer 


operation. If a zero transfer count is specified, 


then the 


values are from the last operation with a nonzero transfer count. 


XA_REGDUMP: 


10$ 


20$ 


MOV ZBL 
MOVAB 
MOV ZBL 
MOV ZWL 
SOBGTR 
MOV ZBL 
MOV ZBL 
MOVL 
SOBGTR 
MOV ZBL 
RSB 

- PAGE 


#11,(RO)+ ; Eleven registers are stored 

UCBSW XA CSRTMP(R5),R1 ; Get address of saved register images 
#8,R2 ; Return’ 8 registers here 

(R1)+,(RO)+ 

R2,10$ ; Move them all 

UCBSW_ XA_DPRN(R5),(RO)+ ; Save datapath register number 

#3,R2_ > And 3 more here 

(R1)+,(RO)+ : Move UBA register contents 


R2,208 
UCBSW_XA_DPRN+1(R5),(RO)+ ; Save Datapath Parity Error Flag 


SAMPLE DRIVER FOR 


~-SBTTL 
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the required controller, and re-enables 


Inputs: 


R5 - Address of UCB 
Outputs: 


Controller is reset, 
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XA_DEV_RESET: 


XA_DEV_RESET - DR11 Device reset routine 


DR1il1s 


XA DEV .RESET - Device reset DRI11l 


This routine raises IPL to device IPL, performs a device reset to 


device interrupts. 


R4 —- Address of Control and Status Register 


controller interrupts are enabled 


PUSHR #°M<RO,R1,R2> ; Save some registers 
DSBINT ; Raise IPL to lock all interrupts 
MOVB #<XA CSRSM MAINT/256>,XA_CSR+1 (R4) 
CLRB XA_CSR+1 (RZ) 
; *** Must delay here depending on reset interval 
MOVZBL #XA RESET DELAY ,R2 : No. of microsecs to wait 
5S MFPR #PRS_ICR,RO > Read interval clock 
10S: MFPR #PRS_ICR,R1 ; Read it again 
CMPL RO,R1 ; Compare both clock readings 
BEQL 10$ ; Repeat until they differ 
SOBGTR R2,5S >: Do this the specified no. of tim 
MOVB #XA_CSRSM_IE,XA CSR(R4) ; Re-enable device interrupts 
ENBINT ; Restore IPL 
POPR #°M<RO,R1,R2> ; Restore registers 
RSB 
XA_END: >: End of driver label 
«END 
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MASSBUS ADAPTER 


The MASSBUS links devices to physical memory. The MASSBUS adapter 
performs the following functions that allow communication between 
devices and memory: 


e Mapping of virtual addresses to physical page frame numbers 


e Buffering of data for transfers from main memory to the 
MASSBUS and vice versa 


e Dispatching interrupts from MASSBUS devices to the SBI 


A MASSBUS adapter supports any combination of mass storage devices. 
Each magnetic tape controller supports up to eight tape drives. Each 
disk controller Supports a single disk drive. The DR70 is a_e general 
purpose interface that actS as a controller for one or _ more 
non-standard devices. Only one controller can transfer data at a 
time. Figure F-1 illustrates a possible MASSBUS configuration. 


MASSBUS —/ 
DISK DISK 


perce ae UNIT 1 UNIT 2 NON-DIGITAL 
DEVICE 


SUB-UNIT SUB-UNIT SUB-UNIT SUB-UNIT 
0 1 2 3 


Figure F-1 MASSBUS Configuration 
This appendix describes the data structures and macros used by DIGITAL 
for its standard magnetic tape and disk products. Customers uSing the 
DR70 should use equivalent techniques. 


The MASSBUS adapter has two sets of registers: 


e Internal registers for the MASSBUS adapter; that is, MBA 
registers 


e External registers for each device on the MASSBUS; that is, 
device registers © 


MASSBUS ADAPTER 


External registers are device-dependent. 


The MASSBUS contains 256 map registers. The driver for a MASSBUS 
device must obtain ownership of the MBA controller before loading map 
registers. 


Each map register is a longword. Bits 21 through 30 of each register 
are reserved; they cannot be written. Use of MBA map registers is 
analogous to use of UBA map registers with the following exceptions: 


e MBA map registers do not contain a byte offset field; the MBA 
virtual address register (VAR) contains the byte offset. 


e MBA map registers do not contain a data path field; the MBA 
has a Single data path. 


Figure F-2 illustrates the mapping of a virtual address to a page 
frame number. 


31 17 16 98 21 O 
VIRTUAL : 
ADDRESS MAP POINTER LONG WORD jevre| 
REGISTER , , 
U—_—~__—_——~/—~_ —Y 


INDEX INTO MAP REGISTERS | 


MAP REGISTERS 


DIRECT 
TRANSFER 
31 30 21 20 7 0 
RESERVED | PHYS. PAGE ADDRESS 
DIRECT 
TRANSFER 
PE SS ee 
27 ak atin na i chins boar nt vn oad whan 0 





SBI ce a 
ADDRESS PHYSICAL PAGE ADDRESS 


Figure F-2 Mapping of a Virtual Address to a Page Frame Number 
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Each MASSBUS adapter has a 2048-longword physical address space. For 
the MASSBUS adapter, bits 10 and 11 of a longword address indicate the 
part of the MBA nexus address space to which the address” refers. 
Addresses can refer to the MBA internal registers, external registers, 
or map registers with the following encodings of bits 10 and ll. 


Bits 11 and 10 Meaning 
0 0 MBA internal registers 
0 1 MBA external registers 


Bits 0 through 6 select the register. 
Bits 7 through 9 select the unit or 
Ssubcontroller. 


1 0 Map register 
Bits 0O through 9 specify the map 
register index. 


Bits 13 through 16 of the address specify the nexus’ position (tr 
number) of the MASSBUS adapter. The address of the nexus position is 
the address of the start of MBA registers. The address of the start 
of MBA space depends on the tr number at which the MASSBUS adapter is 
installed. For examples in this appendix, 20014000 is used as_ the 
Starting address of the MBA registers for the MBA at tr number 0; 
refer to Figure F-3. The programmer of a driver under VAX/VMS- uses 
only virtual addresses; physical addresses are visible only during 
the debugging of the driver. 
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DEVICE REGISTERS 
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MAP REGISTERS 


Figure F-3 Location of MASSBUS Registers 


MASSBUS ADAPTER 
Thus, to address a map address register in the MASSBUS adapter at tr 
10, the driver constructs the following address: 
20014800 + map register index 
20014000 indicates tr 10. 
800 indicates a map register (bits 10 and 11). 


To address a device register, the driver constructs the following 
address: 


20014400 .OR. device .OR. register select 


400 indicates a device reqister (bits 10 and 1l). 


F.1 I/0 DATA BASE FOR MASSBUS DEVICES 


In the simple case (that is, a single-unit controller like a disk 
attached to the MASSBUS), the driver loading procedure constructs a 
channel request block for the MASSBUS adapter. The MASSBUS adapter is 
the device controller for all devices attached to the MASSBUS. Figure 
F-4 illustrates the I/0 data base for a single-unit controller (disk) 
attached to the MASSBUS. 


ASSOCIATED 
DATA BASE 


HARDWARE 
CONFIGURATION 





Figure F-4 I/0 Data Base for MASSBUS Disk Unit 


In the case of a multiunit controller, however, the I/O data base 
created varies slightly from the I/0 data base for a_UNIBUS 
configuration. Multiunit controllers (for example, magnetic tape 
drives on a TMO3 formatter), have two levels of channel request blocks 
and interrupt data blocks. When multiple units are attached to a 
controller that iS attached to the MASSBUS, the driver loading 
procedure creates one CRB and IDB for the MASSBUS adapter and one 
additional CRB and one additional IDB for each multiunit controller 
attached to the MASSBUS. Figure F-5 illustrates the I/O data base 
created for a disk unit and two tape units attached to the MASSBUS. 


F-4 


MASSBUS ADAPTER 


Before a driver can activate a transfer on a unit attached to a 
multiunit controller, the driver must request both the primary 
controller (the TM0O3 controller) and the secondary controller (the 
MASSBUS adapter). 


Nontransfer functions do not require the MASSBUS adapter. For 
example, tape positioning functions require only the magnetic tape 
controller and the unit; the MASSBUS controller is free for other 
operations (for example, data transfers on other units). 
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Figure F-5 I/0 Data Base for MASSBUS Disk and Tape Units 


VAX/VMS defines two levels of interrupt data blocks to dispatch 
interrupts from MASSBUS devices to the corresponding device driver. 
When an interrupt occurs, the VAX/VMS MBA interrupt dispatcher locates 
the channel request block for the MASSBUS adapter. The channel 
request block contains a pointer to the interrupt data block for the 
MASSBUS adapter. 


The interrupt data block contains one entry for each controller 
attached to the MASSBUS. In the case of a single-unit controller, the 
interrupt data block contains a pointer to the unit control block for 
the device. Given the UCB address, the MBA interrupt dispatcher can 
restore the driver. 


In the case of a Solicited interrupt for a multiunit controller, 
however, the interrupt data block contains a pointer to the channel 
request block for the multiunit controller. The pointer addresses’) an 
instruction that transfers control to the controller's own interrupt 
service routine to determine which unit requested the interrupt. The 
second CRB, in turn, contains the pointer to the second interrupt data 


MASSBUS ADAPTER 


block. The interrupt data block contains a pointer to the unit 
control block for each unit attached to the multiunit controller. 


Figure F-6 illustrates the data base for the hardware configuration 
illustrated in Figure F-5. 


If the field IDBSL_ OWNER contains a zero (not filled), the VAX/VMS 
interrupt dispatcher also uses the MBA's Attention Summary register to 
determine the unit requesting the interrupt, as described in Section 
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Figure F-6 I/0 Data Structures Used in Dispatching an Interrupt 


F.2 MBA CONSIDERATIONS FOR DRIVERS 


MASSBUS adapter considerations affect a driver's device unit 
initialization routine, start I/0 routines and, for subcontrollers 
only (magnetic tape), the driver's DPTAB' macro. MBA considerations 
also affect interrupt handling as described in Section F.3. 


F.2.1 Unit Initialization Routine 


In order to perform unit initialization, the driver must refer to’ the 
device registers for the unit. The address of the unit initialization 
routine is specified in a field within the driver dispatch table 


MASSBUS ADAPTER 


(DDTSL UNITINIT). For a single-unit controller, a driver obtains the 
information needed to refer to device registers in the following 
steps: 


e Extracts the unit number from UCBSW_UNIT and stores the unit 
number in UCBSB_ SLAVE 


e Multiplies the slave number by 32 to derive the longword 
offset to the device registers for the drive and stores the 
result in UCBSB SLAVE+1; refer to the descriptions of these 
fields in Appendix A : 


e Assuming that the offset to the device registers is in R3, the 
driver loads the address of the device registers into a 
general register with the following instruction: 


MOVAL MBASL_ERB(R4) [R3] ,R3 


MBASL_ ERB is a fixed offset to the start of the external 
registers. 


R4 contains the address of the MBA configuration register. The 
configuration register is the first register in the MBA nexus space. 


For a multiunit controller, a driver uses the following registers that 
were set up by the driver loading procedure: 


R3 -- Address of the TMO3 device registers 
R4 -- Address of the MBA configuration register 
R5 -- Address of unit control block 


With this information, the driver locates the device registers in the 
following steps: 


e Computes the MBA unit number of the TM03 controller by using 
R3 to determine the number of bytes from the start of the MBA 
external address space to the TM03 device registers’ and 
dividing the reSult by 128; stores the final result in 
UCBSB_ SLAVE 


e Stores the drive offset constant (slave value multiplied by 
32) in UCBS$B_SLAVE+1 


e Performs initialization functions. 


F.2.2 Start I/O Routine 


The I/O data base contains the following information needed by a 
MASSBUS device driver Start I/O routine: 


e For aeSingle-unit controller, the interrupt data block 
contains the address of the adapter's configuration register. 
For a multiunit controller, the interrupt data block contains 
the address of the controller's control/status register; that 
is, the first MBA external register for this controller. 


e The unit control block contains the unit number in UCBSB_ SLAVE 
and the index to the address of the first device register in 
UCB$B_SLAVE+1. 
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The start I/O routine for a MASSBUS device performs the following 
basic functions: 


e Requests controller data channel(s) aS described in Section 
Fegw Zl 


e Clears errors on the MASSBUS adapter by setting -l1 in the MBA 
Status Register; this is a write-ones-to-clear register 
(MASSBUS device registers and MBA registers are a longword). 


e Calls the LOADMBA macro to load map registers as described in 
Section F.2.2.2 


e Sets up sector, track, and cylinder addresses (disk only) 


e Clears drive errors and, if the medium is on line, Starts’ the 
function 


e Waits for device interrupt or timeout 


e Releases controller data channel(s) as described in Section 
Pecece3 


e Finishes the request like other drivers 


F.2.2.1 Requesting a Controller Data Channel - For Single-unit 
controllers, the MASSBUS adapter is the primary controller. For 
multiunit controllers, the subcontroller (device controller) is the 
primary controller, and the MBA is the secondary controller. Drivers 
for single-unit controllers must request the primary controller (MBA 
controller) data channel before they can load MBA map registers. 
Drivers request the primary controller channel by invoking’ the 
REQPCHANL macro. 


Drivers for units attached to a subcontroller must request both’ the 
primary controller data channel and the secondary controller data 


channel before they can load map registers. A tape driver requests 
both channels in the following steps: 


e Invokes the REQPCHANL macro to obtain the primary data channel 


e Invokes the REQSCHANL or REQSCHANLH macro to obtain the 
secondary data channel 


When a driver is performing a nontransfer function such as_ tape 


positioning operation, it does not require the MBA channel. The MBA 
channel is required only for data transfer operations. 


F.2.2.2 Loading Map Registers - MASSBUS device drivers invoke’ the 
LOADMBA macro just prior to a transfer to load the MBA map registers. 
Drivers cannot modify these registers while a transfer is taking 
place. 
LOADMBA expects the following register contents: 

e R4 contains the address of the MBA configuration register. 


e R5 contains the address of the unit control block 


LOADMBA preserves the contents of R3. It uses RO through R2. 
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LOADMBA performs the following steps: 


e Moves the negative value of the transfer byte count 
(UCBSW_BCNT) into MBASL_ BCR, which is the internal MBA byte 
counter register | 


e Moves the byte offset in the first page (UCBSW BOFF) of the 
transfer into MBASL VAR, which is the internal MBA virtual 
address register 


e Extracts a 21-bit page frame number from a page table entry, 
loads the page frame number into each map register needed, and 
sets the register's valid bit 


e Loads a final map register as invalid so that a hardware fault 
does not modify memory 


e Returns to the start I/O routine 


F.2.2.3 Releasing Controller Data Channel(s) - A driver releases’ the 
controller data channels by invoking the RELCHAN macro. RELCHAN 
releases all controller channels (both primary and secondary) for the 
device. To release only the secondary controller channel, a driver 
can invoke the RELSCHAN macro. 


F.2.3  DPTAB Macro 


The device driver for a MASSBUS device attached to a_ subcontroller 
must set the DPTSM SUBCNTRL bit in the FLAGS argument of the DPTAB 
macro. Setting this bit causes the driver loading procedure to create 
a second interrupt data block to describe the subcontroller and to 
hold the address of the sSubcontroller's control/status register. Tt 
also causes creation of the second channel request block. 


F.,3 INTERRUPT HANDLING FOR MASSBUS DEVICES 


The VAX/VMS MASSBUS interrupt handling routine (MBASINT) performs’ two 
functions: 


e For single-unit controllers, it handles the interrupt’ and 
restores the driver in interrupt context at the instruction 
following the wait for interrupt 


e For multiunit controllers, it calls the interrupt service 
routine for the sSubcontroller; for example, it calls the tape 
driver's interrupt service routine 


MBASINT only preserves the contents of R2 through R5. Drivers wishing 
to use RO and Rl must Save and restore them. 
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MBASINT handles interrupts in the following steps: 


1. It obtains the address of the MBA interrupt data block from 
the stack. 


2. From the interrupt data block, it obtains the field 
IDBSL OWNER. IDBSL OWNER contains either zeros’ or a UCB 
address. If it contains zeros, MBASINT proceeds as described 
in steps 1 through 4 of Section F.3.1. 


If IDBSL OWNER contains a UCB address, it indicates the owner 
of the MBA controller. 


3. MBASINT determines whether the device is expecting an 
interrupt. If it is not, MBASINT proceeds as described in 
steps 1 through 4 of Section F.3.1. If the interrupt status 
bit is set, MBASINT clears the bit to indicate that an 
interrupt has occurred. 


4. If the interrupt is expected by the driver of the device that 
owns the channel, MBASINT takes the following steps: 


a. Clears the Attention Summary bit for the MBA slave unit; 
that is, for the device or subcontroller that requested 
the interrupt. This bit is not cleared for 
subcontrollers; the drivers must clear it. 


b. Obtains from the MBA IDB field IDBSL UCBLST (in which 
there are eight entries) the value stored for this 
device; this value is either a UCB address or the 
address of an instruction that transfers control to a 
subcontroller's interrupt service routine 


If the value is not a UCB address, MBASINT proceeds as 
described in steps 1 through 3 of Section F.3.2. 


5. If the value is a UCB address, MBASINT determines whether the 


interrupt iS expected. If the interrupt is not expected, 
MBASINT proceeds as described in steps 1 through 3 of Section 
Ear See a 


6. If the interrupt is expected, MBASINT restores R3, R4, and PC 
and reactivates the driver. When the restored driver invokes 
IOFORK, control returns to this point. 


7. MBASINT proceeds as described in steps 1 through 4 of Section 
Peo 3h 


F.3.1 Looking for Another Request 


Control transfers to this portion of MBASINT as a result of one of the 
following events: 


e An interrupt was requested when no unit owned the MBA 
controller; that is, IDBSL OWNER was zero 


e An interrupt occurred when the owner of the MBA controller was 
not expecting an interrupt 


e When a driver has invoked IOFORK and that fork results in the 
execution of an RSB instruction that returns’ control to 
MBASINT 
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MBASINT performs the following steps to dismiss the interrupt or 
handle the next request: 


1. Clears the MBA status register 


2. Examines the Attention Summary register for a device 
requesting attention 


3. If no device is requesting attention, dismisses the interrupt 


4. If a device is requesting attention, goesS'to step 4 above in 
Section F.3 


The reason that MBASINT always checks the attention summary register 
when an interrupt service routine returns is to determine whether 
another device on the MASSBUS requested an interrupt while the MASSBUS 
owner device was transferring data or while this interrupt was being 
processed. Data transfer functions block’ the interrupts from 
nontransfer functions until the data transfer completes. 


F.3.2 Transferring Control to a Subcontroller's Interrupt Service Routine 


Control transfers to this portion of MBASINT when the device value for 
a MBA slave unit stored in IDBSL UCBLST is the address’ of an 
instruction that transfers control to a subcontroller's§ interrupt 
service routine, for example, a tape controller's interrupt service 
routine. MBASINT performs the following steps: 


1. Moves the PSL onto the top of the stack 


2. Executes a JSB instruction to the dispatch field of the 
Subcontroller's CRB; the dispatch field contains a PUSHR 
instruction that saves R2 through R5 and a JSB instruction to 
the subcontroller's interrupt service routine 


3. The interrupt service routine executes, and after the driver 
forks, the interrupt service routine removes R2 through R5 
from the stack and executes an REI instruction. The REI 
instruction removes the PSL and MBASINT's return address from 
the stack and returns control to MBASINT. MBASINT proceeds 
as described in steps 1 through 4 of Section F.3.1. 


F.3.3 Handling Unsolicited Interrupts 


When MBASINT finds that an unsolicited interrupt occurred (step 5 of 
Section F.3), it performs the following steps: 


1. Obtains the address of the driver's unsolicited interrupt 
routine from the driver dispatch table 


2. Calls the routine at that address 


3. When the driver invokes IOFORK, MBASINT proceeds as described 
in steps 1 through 4 of Section F.3.1 
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ACP 
See Ancillary Control Process. 


adapter control block (ADP) 
A structure in the I/O data base that describes either a UNIBUS or 
MASSBUS adapter. 


ADP 
See adapter control block, 


allocate a device 

To reserve a particular device unit for exclusive use. A user process 
can allocate a device only when that device is not allocated by any 
other process. 


Ancillary Control Process (ACP) 
A process that acts aS an interface between user software and an I/O 
driver. An ACP provides functions supplemental to those performed in 
the driver, such as file and directory management. Three examples of 
ACPs are: the Files-ll ACP (FI11ACP), the magnetic tape ACP (MTAACP), 
and the networks ACP (NETACP). 


assign a channel 

To establish the necessary software linkage between a user process and 
a device unit before a user process can communicate with that device. 
A user process requests the system to assign a channel and the’ system 
returns a channel number. 


AST 
See Asynchronous System Trap. 


ASTLVL 
See Asynchronous System Trap Level. 


Asynchronous System Trap (AST) 

A software-simulated interrupt to a user-defined service routine. 
ASTS enable a user process to be notified asynchronously with respect 
to its execution of the occurrence of a Specific event. If a user 
process has defined an AST routine for an event, the system interrupts 
the process and executes the AST routine when that event occurs. When 
the AST routine exits, the system resumes the process at the point 
where it was interrupted. 
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Asynchronous System Trap Level (ASTLVL) 

A value kept in an internal processor register that is the highest 
access mode for which an AST is pending. The AST does not occur until 
the current access mode drops in privilege (rises in numeric value) to 
a value greater than or equal to ASTLVL. Thus, an AST for an access 
mode will not be serviced while the processor is executing in a more 
privileged access mode. 


base register 
A general register used to contain the address of the first entry ina 
list, table, array, or other data structure. 


buffered data path 

A UNIBUS adapter data path that transfers 32 or 44 bits of data in a 
Single SBI transfer. The UNIBUS adapter has 15 buffered data paths 
and one direct data path. 


buffered I/0 
See system buffered I/O. 


bugcheck 
The operating system's internal diagnostic check. The system logs the 
failure and crashes the system. 


call instructions 


The processor instructions CALLG (Call Procedure with General Argument 
List) and CALLS (Call Procedure with Stack Argument List). 


CCB 
See channel control block. 


channel 

A logical path connecting a user process to a physical device unit. A 
user process requests the operating system to assign a channel to a 
device so the process can communicate with that device. See also 
controller data channel. 


channel control block (CCB) 

A structure in the I/O data base maintained by the Assign I/O channel 
system service to describe the device unit to which a channel is 
assigned. 


channel request block (CRB) 

A structure in the I/O data base that describes the activity on a 
particular controller. The channel request block for a controller 
contains pointers to the wait queue of drivers ready to access a 
device through the controller. 


configuration register 
A control/status register for an adapter, for example a_UNIBUS 


adapter. It resides in the adapter's I/O space. 


Glossary-2 


connect-to-interrupt 

A function by which a process connects to a device interrupt vector. 
To perform a connect-to-interrupt, the process must map to the program 
I/O space containing the vector. 


console 

The manual control unit integrated into the central processor. The 
console includes a serial line interface connected to a hard-copy 
terminal. This enables the operator to start and stop the _ system, 
monitor system operation, and run diagnostics. 


console terminal 
The hard-copy terminal connected to the central processor console. 


context 


The environment of an activity. See also process context, hardware 
context, and software context. 


controller data channel 
A logical path to which a driver for a device on a multiunit 
controller must be granted access before it can activate a device. 


control/status register (CSR) 
A control/status register for a device or controller. It resides in 
the processor's I/O space. 


CRB 
See channel request block. 


CSR 
See control/status register. 


data base 
(1) All the occurrences of data described by a data base management 
system. 


(2) A collection of related data structures. 


data structure 


Any table, list, array, queue, or tree whose format and access 
conventions are well-defined for reference by one or more images. 


DDB 
See device data block. 


DDT 
See driver dispatch table. 


device data block (DDB) 
A structure in the I/0 data base that identifies the generic 
device/controller name and driver name for a set of devices attached 
to the same controller. 
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device interrupt 

An interrupt received on interrupt priority levels 20 through 23. 
Device interrupts can be requested only by devices, controllers, and 
memories. 


device register 
A location in device controller logic used to request device functions 
(such as I/O transfers) and/or report Status. 


device unit 

One drive and its controlling logic, for example, a disk drive or 
terminal. Some controllers can have several device units connected to 
a Single controller; for example, masSs storage controllers. 


diagnostic 
A program that tests hardware, firmware, peripheral operation, logic, 
or memory and:reports any faults it detects, 


direct data path 

A UNIBUS adapter data path that transfers 16 bits of data in a_ single 
SBI transfer. The UNIBUS adapter has one direct data path and 15 
buffered data paths. 


direct I/0 

An I/O operation in which VAX/VMS locks the pages containing the 
associated buffer in physical memory for the duration of the I/O 
operation. The I/O transfer takes place directly from the process 
buffer. Contrast with system buffered I/O. 


DPT 
See driver prologue table. 


drive 

The electromechanical unit of a mass storage device system on which a 
recording medium (disk cartridge, disk pack, or magnetic tape reel) is 
mounted. 


driver 


The set of code and tables that handles physical I/O operations to a 
device. . | 


Griver dispatch table (DDT) 


A table in the I/O driver that lists the entry point addresses of 
standard driver routines and the sizes of diagnostic and error logging 
buffers for the device type. 


driver fork level 


The interrupt priority levels at which a driver fork process executes, 
that is, IPLS 8 through 11. Every unit control block indicates the 


driver fork level for its unit. 
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driver prologue table (DPT) 
A table in the driver that describes the driver and the device type to 
the VAX/VMS procedure that loads drivers into the system. 


driver start I/O routine 
See start I/O routine. 


ECC 
Error Correction Code. 


error logger 

A system process that empties the error log buffers and writes’ the 
error messageS into the error file. Errors logged by the system 
include memory system errors, device errors and timeouts, and 
interrupts with invalid vector addresses. 


exception 

An event detected by the hardware or software (other than an interrupt 
Or jump, branch, case, or call instruction) that changes the normal 
flow of instruction execution. An exception is always caused by the 
execution of an instruction or set of instructions (whereas an 
interrupt is caused by an activity in the system independent of the 
current instruction). There are three types of hardware exceptions: 
traps, faults, and aborts. Examples are: attempts to execute a 
privileged or reserved instruction, trace traps, compatibility mode 
faults, breakpoint instruction execution, and arithmetic traps. 


executive 

The generic name for the collection of procedures included in the 
operating system software that provide the bhasic control and 
monitoring functions of the operating system. 


FDT 
See function decision table. 


FDT routines 
Driver routines called by the Queue I/O Request system service to 
perform device-dependent preprocessing of an I/O request. 


fork block 

That portion of a unit control block that contains a driver's context 
while the driver is waiting for a resource. A driver awaiting the 
processor resource has its fork block linked into the fork queue. 


fork dispatcher 

A VAX/VMS interrupt service routine that is activated by a_ software 
interrupt at a fork interrupt priority level. Once activated, it 
dispatches driver fork processes from a driver fork queue until no 
processes remain in the queue for that IPL. 
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fork process 
A fork process is a minimal context process that executes code under a 


series of constraints: it executes at raised interrupt priority 
levels; it uses RO through R5 only (other registers must be saved and 
restored); it executes in system virtual address space; it is only 


allowed to refer to and modify static storage that is never modified 
by higher interrupt priority level code. VAX/VMS uses software 
interrupts and fork processes to synchronize executive operations. 


fork queue 
A queue of driver fork blocks that are awaiting activation at a 
particular IPL by the VAX/VMS fork dispatcher. 


function code 
See I/O function code. 


function decision table (FDT) 

A table in the driver that lists all valid function codes for the 
device and lists the addresses of I/0 preprocessing routines 
associated with each valid function. 


function modifier 
See I/O function modifier. 


generic device name 

A device name that identifies the type of device but not a_ particular 
unit; a device name in which the specific controller and/or unit 
number 1S omitted. When discussing device drivers, the generic device 
name contains neither the controller designation nor the unit number, 
for example, DB. 


hardware context 

The values contained in the following registers while a process is 
executing: the PC; the PSL; the 14 general registers (RO through 
R13); the four processor registers (POBR, POLR, PIBR and PI1LR) that 
describe the process virtual address space; the SP for the current 
access mode in which the processor is executing; plus the contents to 
be loaded in the SP for every access mode other than the current 
access mode. While a process is executing, its hardware context is 
continually being updated by the processor. While a process is not 
executing, its hardware context is stored in its hardware PCB. 


hardware process control block (hardware PCB) 
A data structure known to the processor that contains the hardware 
context when a process is not executing. A process's hardware PCB 


resides in its process header (PHD). 


IDB 
See interrupt data block. 
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interrupt 

An event other than an exception or branch, jump, case, or call 
instruction that changes the normal flow of instruction execution. 
Interrupts are generally external to the process executing when the 
interrupt occurs. See also device interrupt, software interrupt, and 
urgent interrupt. 


interrupt data block (IDB) 

A structure in the I/O data base that describes the characteristics of 
a particular controller and points to devices attached to that 
controller. 


interrupt priority level (IPL) 

The interrupt level at which a software or hardware interrupt is 
generated. There are 32 possible interrupt priority levels: IPL 0 is 
lowest, 31 is highest. The levels arbitrate contention for processor 
service. For example, a device cannot interrupt the processor if the 
processor is currently executing at an interrupt priority level 
greater than the interrupt priority level of the device's interrupt 
service routine. 


interrupt service routine (ISR) 
A routine executed when a device interrupt occurs. 


interrupt stack (IS) 

The system-wide stack used when executing in interrupt’ service 
context. At any time, the processor is either in a process context 
executing in user, supervisor, executive, or kernel mode, or in 
system-wide interrupt service context operating in kernel mode, as 
indicated by the interrupt stack and current mode bits in the PSL. 
The interrupt stack is not context switched. 


interrupt stack pointer (ISP) 

The stack pointer for the interrupt stack. Unlike the stack pointers 
for process context stacks, which are Stored in the hardware PCB, the 
interrupt stack pointer is stored in an internal processor register. 


interrupt vector 
See vector. 


I/O data base 

A collection of data structures that describes 1/0 requests, 
controllers, device units, volumes, and device drivers in a VAX/VMS 
system. Examples are the driver dispatch table, driver prologue 
table, device data table, unit control block, channel request block, 
I/O request packet, and interrupt data block. 


I/O driver 
See driver. 


I/O function 
An I/O operation interpreted by the operating system and typically 
resulting in one or more physical I/O operations. 
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I/O function code 

A 6-bit value specified in a Queue I/O Request system service that 
describes the particular I/O operation to be performed (such as, read, 
write, rewind). 


I/O function modifier 

A 10-bit value specified in a Queue I/O Request system service that 
modifies an I/O function code (for example, read terminal input no 
echo). 


I/O lockdown 


The state of a page such that it cannot be paged or swapped out of 
memory. 


I/O request packet (IRP) 

A structure in the I/O data base that describes an individual I/0 
request. The Queue I/O Request system service creates an I/O request 
packet for each I/O request. VAX/VMS and the driver of the target 
device use information in the I/0 request packet to process the 
request. 


I/O rundown 
An operating system function in which the system cleans up any I/O in 
progress when an image exits. 


I/O space 
The regions of physical address space that contain the configuration 
registers, and device control/status and data registers. These 


regions are physically discontiguous. 


I/O status block (IOSB) 
A data structure associated with the Queue I/O Request system service. 


This service optionally returns a status code, number of bytes 
transferred, and device/function-dependent information in an I/O 


status’ block. The information returned is not returned from the 
service call, but filled in by VAX/VMS when the I/O request completes. 


IPL 
See interrupt priority level. 


IRP 
See I/O request packet. 


ISP 
See interrupt stack pointer. 


ISR 
See interrupt service routine. 
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limit 

The size or number of given items requiring system resources (Such as 
mailboxes, locked pages, I/0 requests, or open files) that a job is 
allowed to have at any one time during execution, as specified by the 
system manager in the user authorization file. See also quota. 


locking a page in memory 

Making a page in an image ineligible for either paging or swapping. A 
page stays locked in physical memory until VAX/VMS specifically 
unlocks it. 


logical I/O function 


A set of I/O operations (for example, read and write logical block) 
that allow restricted direct access to device level I/O operations 


uSing logical block numbers. 


mailbox 

A software data structure that is treated as a record-oriented device 
for general interprocess communication. Communication using a mailbox 
is similar to other forms of device-independent I/O. Senders write to 
a mailbox; the receiver reads from that mailbox. Some system-wide 
mailboxes are defined: the error logger and OPCOM~ read from 
system-wide mailboxes. 


MBA 
MASSBUS Adapter. 


offset 

A fixed displacement from the beginning of a data structure. System 
offsets for items within a data structure normally have an associated 
symbolic name used instead of the numeric displacement. Where symbols 
are defined, programmers always reference the symbolic names for items 


in a data structure instead of using the numeric displacement. 


page frame number (PFN) 
The high-order 21 bits of the physical address of a page in physical 
memory. 


page table entry (PTE) 

The data structure that identifies the physical location and status of 
a page of virtual address space. When a virtual page is in memory, 
the PTE contains the page frame number needed to map the virtual page 
to a physical page. When it is not in memory, the page table entry 
contains the information needed to locate the page on secondary 
storage (disk). 


PCB 
See Process Control Block. 


PFN 
See page frame number. 
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physical address 

The address used by hardware to identify a location in physical memory 
or on directly-addressable secondary storage devices such as a disk. 
A physical memory address consists of a page frame number’ and the 
number of a byte within the page. A physical disk block address 
consists of a cylinder or track and sector number. 


physical address space 

The set of all possible 30-bit physical addresses that can be used to 
refer to locations in memory (memory space) or device registers (I/O 
Space). 


physical I/O functions 


A set of I/O functions that allows access to all device level I/0 
operations except maintenance mode. 


PID 
See process identification. 


process 

The basic entity scheduled by the system software that provides’ the 
context in which an image executes. A process consists of an address 
Space and both hardware and software context. 


process context 
The hardware and software contexts of a process. 


process control block (PCB) 

A data structure used to contain process context. The hardware PCB 
contains the hardware context. The software PCB contains the software 
context, which includes a pointer to the hardware PCB. 


process identification (PID) 
A 32-bit binary value that uniquely identifies a process. Each 
process has a process identification and a process name. 


process I/O channel 
See channel. 


process page tables 
The page tables used to describe process virtual memory. 


process priority 

The priority assigned to a process for scheduling purposes. The 
operating system recognizes 32 levels of process priority, where 0 is 
low and 31 high. Levels 16 through 31 are used for real-time 
processes. The system does not modify the priority of a real-time 
process (although the system manager or process itself may). Levels 0 
through 15 are used for normal processes. The system may temporarily 


increase the priority of a normal process based on the activity of the 
process. 
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program section (psect) 

A portion of a program with a given protection and set of storage 
management attributes. Program sections that have the same attributes 
are gathered together by the linker to form an image section. 


PTE 
See page table entry. 


QIO 

Queue I/O Request syStem service. The VAX/VMS system service that 
services SQIO and SQIOW requests. The Queue I/0 Request system 
service prepares an I/O request for processing by the driver. and 
performs device-independent preprocessing of the request. This system 
service also calls driver FDT routines. 


quota 

The total amount of a system resource, Such as CPU time, that a job is 
allowed to use in an accounting period, as specified by the system 
manager in the user authorization file. See also limit. 


return status code 
See status code, 


SBI 
See Synchronous Backplane Interconnect. 


small process 

A system process that has no control region in its virtual address 
space and has an abbreviated context. Examples are the working set 
Swapper and the null process. A small process is scheduled in the 
Same manner aS user processes, but must remain resident until it 
completes execution; that is, it cannot be swapped. 


software context 
The context maintained by VAX/VMS to describe a process. See software 
process control block (PCB). 


software interrupt 
An interrupt generated on interrupt priority level 1 through 15, which 
can be requested by software. 


software process control block (software PCB) 

The data structure used to contain a process's software context. The 
operating system defines a software PCB for every process when the 
process is created. The software PCB includes the following kinds of 
information about the process: current state; storage address if it 
is swapped out of memory; unique identification of the process; and 
address of the process header (which contains the hardware PCB). The 
software PCB resides in system region of virtual address space. It is 
not Swapped with a process. 


Start I/O routine 


The routine in a device driver that is responsible for obtaining 
necessary resources, for example, the controller data channel, and 


activating the device unit. 


Glossary-1l 


status code 

A longword value that indicates the success or failure of a_ specific 
function. For example, system services always return a status code in 
RO upon completion. 


SVA 
See system virtual address. 


Synchronous Backplane Interconnect (SBI) 
The part of the hardware that interconnects the processor, memory 
controllers, MASSBUS adapters, the UNIBUS adapter. 


system buffered I/0 

An I/O operation, such as terminal or mailbox I/0, in which an 
intermediate buffer from the system buffer pool is used instead of a 
process-specified buffer. Contrast with direct I/0. 


System Page Table (SPT) 

The data structure that maps the system virtual addresses, including 
the addresses used to refer to the process page tables. The SPT 
contains one PTE for each page of system virtual memory. The physical 
base address of the SPT is contained in a processor register called 
SBR. 


system virtual address (SVA) 


A virtual address identifying a location mapped to an address in 
system space. 


timeout 
The expiration of the time limit in which a device is to complete an 
I/O transfer. The driver's wait for interrupt request specifies the 


timeout limit. 


timer 

A system process that maintains the time of day and the date. It also 
scans for device timeouts and performs time-dependent scheduling upon 
request. The timer interrupt service routine creates the timer 
process. 


UBA 
UNIBUS Adapter. 


UCB 
See unit control block. 


unit control block (UCB) 

A structure in the I/O data base that describes the characteristics of 
and current activity on a device unit. The unit control block also 
holds the fork block for its unit's device driver; the fork block is 
a critical part of a driver fork process. The UCB also provides a 
static storage area for the driver. 
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unit initialization routine 

The routine that readies controllers and device units for operation. 
Controllers and device units require initialization after a power fail 
and during the driver loading procedure. 


urgent interrupt 

An interrupt received on interrupt priority levels 24 through 31. 
These can be generated only by the processor for the interval clock, 
serious errors, and power fail. 


vector 

(1) An interrupt or exception vector is a storage location known to 
the system that contains the starting address of a routine to be 
executed when a given interrupt or exception occurs. The system 
defines separate vectors for each interrupting adapter and for 
classes of exceptions. Each system vector is a longword. 


(2) For the purpose of exception handling, users can declare up_ to 


two software exception vectors (primary and secondary) for each 
of the four access modes. Each vector contains the address of a 
condition handler. 


(3) A one-dimensional array. 


virtual I/O functions 


A set of I/O functions that must be interpreted by an ancillary 
control process. 


wait for interrupt request 

A request made by a driver's start I/O routine after it activates a 
device. The request causes the driver fork process to be suspended 
until the device requests an interrupt or the device times out. 


XDELTA 
A tool for debugging operating systems and drivers. 
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INDEX 


A 


Aborting I/O after timeout, 12-5 
Activating a fork process from 


fork queue, 5-14 

Activating the device, 5-12, 9-2, 
9-6, 10-6 

Adapter control block (ADP), 1-7, 
10-1, A-27 

Address mapping for DMA transfers, 
4-2 


ADPSB_NUMBER, A~30 
ADPSB TYPE, A-30 
ADPSL_CRB, A-31 
ADPSL CSR, A-30 
ADPS$L_DPQBL, A-31 
ADPSL DPQFL, A-31 
ADPSL_INTD, A-32 
ADPSL LINK, A-30 
ADPSL_MROBL, A-32 
ADPSL MROQFL, A-31l 
ADPS$L_ VECTOR, A-31 
ADPSW ADPTYPE, A-30 
ADPSW DPBITMAP, A-32 
ADPSW MRBITMAP, A-32 
ADPSW SIZE, A-30 
ADPSW TR, A-30 
Allocation of an I/O request 
packet, 5-7 
Allocation of map registers, 10-4 
Assembling driver sources, 14-1 
Assigning an I/O channel, 5-3 
Asynchronous system traps (ASTS), 
kernel mode, 5-17 
user mode, 5-17 
Autoconfiguration, 14-7 


AUTOCONFIGURE command, 14-7 


B 


Base registers, 
setting, 15-1l 
Blocking interrupts, 9-6 
Bootstrapping the system with 
XDELTA, 15-1 
Breakpoints, 


clearing, 15-10 


displaying, 15-11 
inserting in the source code, 
15-3 


proceeding from, 15-11 

setting, 15-10 

setting complex, 15-13 
Buffered data path, 4-5 


permanent allocation of, 10-3 


Buffered data path, 
purging, 4-7, 10-7 


(Cont. ) 


release of, 10-8 
requesting with no wait, 10-3 
requesting with wait, 10-2 
Buffered I/O functions, | 
selection of, 7-9 
Buffered I/O operations, 1-15 


FDT routines for, 8-6 
implications for I/O post- 
processing, 8-7 
kernel mode AST for read, 8-8 
Byte offset data transfers, 4-7 


C 


Calculating the base of driver 
code, 15-4 
Cancel I/O on Channel system 
service, 13-4 
Cancel I/O routine, 
context for, 13-5 
CASE macro, B-1l 
CCBSB _AMOD, A-39 
CCBSB STS, A-39 
CCBSL DIRP, A-39 
CCBSL UCB, A-39 
CCBSL WIND, A-39 
CCBSW IOC, A-39 
Channel, 
process I/O channel vs. con- 
troller data channel, 5-5 
requesting the controller data 
channel, 9-3 
Channel arbitration routine, 
Channel assignment, 
process, 5-3 
Channel control block (CCB), 
1-7, A-38 
Channel request block 
5-5, A-22 
for MASSBUS devices, F-4 
Checking for power failure, 9-fA 
Checking process I/O request 
quotas, 5-7 
Clearing breakpoints, 15-10 
Close and Display Next Location 
command, 15-9 
Coding conventions, 6-1 
Coding DMA transfers, 10-1 
Coding driver tables, 7-1 
Coding FDT routines, 8-1 
Coding ‘interrupt service routines, 
li-1 
Coding start I/O routines, 9-1] 
COMSDELATTNAST, C-1l 


l-ll, 13-4 


3-14 


(CRB), 1-6, 


Index-l 


INDEX 


COMSDRVDEALMEM, C-2 
COMSFLUSHATTNS, C-2 
Command files for booting with 
XDELTA, 
DBAXDT, 15-1 
DMAXDT, 15-1 
Competing for controller data 
channel, 3-15 
COMSPOST, 8-17, C-3 
COMSSETATTNAST, C-4 
Completing the I/O request, 
12-1 
Computing starting address of 
transfer, 10-6 
Computing transfer length, 9-5 
Configuration rules, 14-14 
CONNECT command, 14-3, 15-2 
Constraints for fork process 
execution, 3-14 
Context, 
for cancel I/O routine, 13-5 
for FDT routine execution, 8-l, 
8-2 
for fork process, 1-4 
for initialization routine, 
13-3 
for interrupt, 1-3, 11-3 
for start I/O routine, 9-1] 
Controller data channel, 
competing for, 3-15 
releasing after transfer, 
requesting, 9-3 
requesting for MASSBUS device, 
F-8 
Controller initialization routine, 
13-1 
Conventions, 
coding, 6-1 
followed by FDT routines, 8-2 
register usage, 6-3 
register usage in I/O space, 
§-3 
terminology, xili 
CRBSB MASK, A-24 
CRBSB TYPE, A-23 
CRBSL INTD, 7-2, 9-5, 10-3, 10-4, 
10-7, 13-2, 14-5, A-24 
CRBSL INTD+2, 11-3, A-24 
CRBSL_INTD+4, 7-2 
CRBSL LINK, A-24 
CRBSL WQOBL, A-23 
CRBSL WOFL, A-23 
CRBSW REFC, A-24 
CRBSW SIZE, A-23 
Creating a driver fork process 
for start I/0, 5-10 
CSR addresses, 
Fixed and floating, 


5-16 r 


12~2 


14-7 


Data channel, see controller data 
channel 
Data path, 4-3 to 4-8 


buffered data paths, 4-5 

byte offset data transfers, 4-7 

direct data path, 4-4 

longword-aligned 32-bit random 

access mode, 4-7 
purging buffered data paths, 
4-7 

DBAXDT command file, 
DDBSB_TYPE, A-9 
DDBSL ACPD, A-9 
DDBSL_ DDT, 7-2, A-9 
DDBSL LINK, A-9 
DDBSL_UCB, A-9 
DDBST DRVNAME, A-9 
DDBS$T_ NAME, A-9 
DDBSW SIZE, A-9 
DDTAB macro, 7-6 
DDTSL_ALTSTART, A-35 
DDTSL CANCEL, A-34 
DDT$L_FDT, A-33 
DDTSL_REGDUMP, A-34 
DDTSL START, A-33 
DDTSL UNITINIT, A-35 
DDTSL_UNSOLINT, A-33 
DDTSW DIAGBUF, A-34 
DDTSW_ERRORBUF, A-34 
Debugging a device driver, 

techniques, 15-14 
Defining device-specific function 

codes, 7-7 

DELTA debugging utility, 

commands, 15-14 

linking with user programs, 


15-1 


15-1 


Loe 


15-14 
Destroying register contents, 
15-5 
Device activation, 2-6, 5-12, 
9-2, 9-6, 10-6 


Device activation bit mask, 9-5 
Device configuration, 14-9 
example of a UNIBUS config- 
uration, 14-15 
rules, 14-14 
Device data block (DDB), 1-64 
5-5, A-8 
Device dependence, 1-4 
Device-dependent cancel I/0 
routine, 13-5 
Device-dependent I/0 post- 
processing, 12-3 
Device driver, 
functions of, 1-9 
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INDEX 


Device independence, 1-4 
Device-independent cancel I/0 
routine, 13-5 
Device interrupt, 
delivering to a driver, 11-1 
handling of, 5-13 
responding to, 9-8 
unsolicited, 11-5 
waiting for, 9-6 
Device IPLs, 3-6 
Device registers, 
incorrect references to, 15-15 
opening with XDELTA, 15-15 
reading and writing, 4-2 
Device-specific function codes, 
7-7 
Device table for SYSGEN, 14-9 
Device timeout, 
wait for interrupt or, 9-6 
Device timeout handler, 1-1l, 
12-4 
Direct data path, 4-4 
requesting a, 10-3 
Direct I/O functions, 7-9 
Direct I/O operations, 1-15 
FDT routines for, 8-4 
Direct memory access (DMA), 1-15 
Direct memory access transfers, 
4-] 
Dispatching fork processes, 3-12 
Displaying breakpoint list, 15-11 
Display Range command, 15-9 
DMA, see Direct memory access 
DMAXDT command file, 15-1 
DPTAB macro, 7-1 
DPTSB ADPTYPE, A-36 
DPTSB_ FLAGS, A-36 
DPTSB REFC, A-36 
DPTSB_ TYPE, A-36 
DPTSL BLINK, A-36 
DPTSL FLINK, A-36 
DPTSM NOUNLOAD, 7-3 
DPTSM_SVP, 7-3 
DPT STORE macro, 7-3, B-2 
DPTST_NAME, A-38 
DPTSW INITTAB, A-37 
DPTSW_REINITTAB, A-37 
DPTSW SIZE, A-36 
DPTSW UCBSIZE, A-37 
DPTSW UNLOAD, A-38 
DPTSW VERSION, A-38 
Driver debugging, 15-1 
Driver dispatch table (DDT), 
7-1, A-33 
creation of, 7-5 
Driver fork IPLs (8 through 1l), 
3-7 
Driver fork process, 1-3 
context of, 9-1 
creation for start I/O routine, 
5-11 


Driver linking, 14-1 
Driver loading, 14-1, 15-2 
initialization during, 13-2 
Driver program sections, 14-1 
Driver prologue table (DPT), 
7-1, A-35 
Driver routines, 
cancel I/O routine, 1-11, 13-4 
device timeout handler, 1-11, 
12-4 
error logging routine, 1-11, 
13-6 
FDT routines, 1-10, 8-1 
initialization routines, 1-10 
13-1 
interrupt service routine, 
1-11, 11-1 
I/O completion, 12-1 
Start I/O routine, 1-10, 9-1 
Driver source assembly, 14-1 
Driver tables, 
coding of, 7-1 
Driver template, 6-1, 6-5 
DSBINT macro, 12-6, B-2 
format of, 3-11 
Dump routines (register), 13-64 


E 


ENBINT macro, 3-11, B-2 
format of, 3-12 
ERLSDEVICERR, 13-6, C-6 
ERLSDEVICTMO, 13-6, C-6 
ERLSRELEASEMB, 12-3, C-6 
Error logging routine, 1-1l, 


13-6 

Examining the vector jump table, 
15-4 

Examining UCB, IPR, and PSL, 
15-6 


Example of bootstrapping the 
System with XDELTA, 15-2 
Example of unsolicited interrupt 

handling, 11-6 
Examples of table-generating 
macro invocations, 
DDTAB macro, 7-4 
DPTAB macro, 7-5 
DPT STORE macro, 7-5 
FUNCTAB macro, 7-10 
EXESABORTIO, 8-6, 8-8, 8-13, C-7 
EXESALLOCBUF, C-8 
use for buffered I/0, 8-6 
EXESALLOCIRP, C-9 
EXESALONONPAGED, C-9 
EXESALTQUEPK, 8-5, 8-17, C-9 
EXESBUFFRQUOTA, C-10 
EXESBUFQUOPRC, C-1l 
EXESCANCEL, 13-4 
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Execute string command to XDELTA, 
15-12 

EXESDEANONPAGED, C-1ll 

EXESFINISHIO, 8-5, 8-14, C-12 

EXESFINISHIOC, 8-5, 8-6, 8-14, 
C-12 

EXESFORK, C-12 

EXESFORKDSPTH, C-13 


EXESINSERTIRP, C-13 
EXESINSIOQ, 8-16, C-14 
EXESIOFORK, 10-7, 11-5, 15-6, 
C-15 

function of, 12-1 
EXESMODIFY, C-16 
EXESMODIFYLOCK, C-17 
EXESMODIFYLOCKR, C-18 
EXESONEPARM, 8-9, C-20 
EXESQIODRVPKT, 8-5, 8-13, C-20 
EXESQIORETURN, C-21 
EXESREAD, 8-9, C-21 

use for buffered I/O, 8-4 
EXESREADCHK, 8-9, C-21 

use for buffered I/0, 8-6 
EXESREADCHKR, C-22 
EXESREADLOCK, 8-9, C-22 
EXESREADLOCKR, C-22 
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FDT entry, 5-9 
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3-13 
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FORK macro, B-2 
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5-15 
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Fork process dispatching, 3-13 
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IPL$ MAILBOX, 3-9 
IPLS POWER, 3-7 
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I/O operations, 
buffered vs. direct, 1-15 
I/O postprocessing, 5-17 
by driver, 2-8, 12-1 
by VAX/VMS, 2-8, 12-3 
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9-2, A-6 7 

IRPSL UCB, A-4 

IRPS$L WIND, A-4 

IRPSW ABCNT, A-7 


IRPSW_BCNT, 8-6, 8-8, 8-9, 9-2, 


A-6 
IRPSW_BOFF, 8-7, 8-8, 8-16, 
9-2, A-6 
IRPSW_CHAN, 13-5, A-5 
IRPSW_FUNC, 8-9, 9-4, A-4 
IRPSW_OBCNT, A-7 
IRPSW_SIZE, A-3 
IRPSW_STS, 8-6, 8-8, 8-9, A-5 


INDEX 


J 


JIBSL_BYTCNT, 8-7 
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Linking a driver, 14-1 
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15-2 
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(XDELTA), 15-11 
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Loading UBA map registers, 9-4, 
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LOADUBA macro, 10-5, B-3 

Longword-aligned 32-bit transfer 
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~ 15-6 
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4-7, 10-7 
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EXESALTQUEPKT, 8-5, 8-17, C-9 
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EXESWRITELOCK, C-28 
EXESWRITELOCKR, C-29 
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IOCSINITIATE, C-35 
IOCSIOPOST, C-36 
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SAVIPL macro, B-4 
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mapping to UNIBUS, 4-2 
Sending a message to the opera- 
tor, 12-4 
SETIPL macro, B-4 
format of, 3-1ll 
Setting an XDELTA base register, 
15-5, 15-11 
Setting base registers, 15-1] 
Setting breakpoints, 15-10 
Setting complex breakpoints, 
15-13 
SHOW/DEVICE command, 14-6, 15-3 
Show Value command, 15-10 
SOFTINT macro, B-4 
format of, 3-12 
Software IPLS, 3-1 
Solicited interrupt, 
servicing an, 11-4 
Start I/O routine, 1-10, 5-12 
coding an, 9-1 
execution context, 9-1 
for MASSBUS device, F-7 
Status, 
Saving, 12-3 
Step Instruction command, 15-10 
Synchronization, 1-7 
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interrupt priority levels, 1-7 
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SYSGEN'S autoconfiguration, 14-8 
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UNIBUS adapter, 4-1, 10-1 
UNIBUS device configuration, 
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11-5 
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example of, 11-6 
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format of, 9-7 Step Instruction, 15-10 
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X XDELTA interrupt, 
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